操作 系统 、 应 用 服务 和 业务 逻辑 ， 都 在 不 停 地 产生 日 志 数 据 。 过 去 ， 日 志 数 据 基本 都 存在 单机 磁盘 上 ， 只 能 用 来 做 临时 的 事后 分 析 和 审计 ; 有 Hadoop 以 后 ， 大 家 渐渐 习惯 将 日 志 收集 到 HDFs 中 ， 然 后 
每 天 运行 MapReduce 任 务 做 统计 报表 。 但 是 ， 面 对 诸如 “新 上 线 的 版 本 过 去 几 分 钟 在 各 地 反馈 如 何 ” “昨天 23: 40 左 右 这 个 投诉 用 户 有 没有 异常 ”这 种 即时 的 开放 性 问题 ， 传 统 的 日 志 处 理 方案 显得 非常 
笨拙 和 低 效 ， 因 为 解答 没有 唯一 套路 ,需要 尝试 下 钻 挖 握 才能 得 出 答案 。 复 杂 多 变 的 实时 数据 分 析 需 求 ， 需 要 的 是 灵活 快捷 的 响应 处 理 。Splunk 公 司 正 是 凭借 着 自己 在 这 个 大 数据 细 分 领域 的 一 校 独 秀 ， 成 
为 百 亿美 元 级 的 明星 公司 。 但 是 Splunk 每 GB 高 达 4500 美 元 的 报价 ， 又 让 人 望而却步 。 直 到 ELK stack 出 现 后 ， 大 家 才 有 了 可 选择 的 开源 产品 。 


ELK stack 是 以 Elasticsearch、Logstash、Kibana 三 个 开源 软件 为 主 的 数据 处 理工 具 链 ， 在 实时 数据 检索 和 分 析 场 合 ， 三 者 通常 是 配合 使 用 ， 而 且 又 先后 归于 Elastic.co 公 司 名 下 ， 故 有 此 简称 。 


ELK stack 具 有 如 下 几 个 优点 : 


“ 处 理 方式 灵活 。Elasticsearch 是 实时 全 文 索引 ， 不 需要 像 Storm 那 样 预先 编程 才能 使 用 。 

- 配置 简易 上 手 。Elasticsearch 全 部 采用 JSON 接 口 ，Logstash 是 Ruby DSL 设 计 ， 都 是 目前 业界 最 通用 的 配置 语法 设计 。 
“ 检索 性 能 高 效 。 虽 然 每 次 查询 都 是 实时 计算 ， 但 是 优秀 的 设计 和 实现 基本 可 以 达到 百 亿 级 数据 查询 的 秒 级 响应 。 

- 集群 线性 扩展 。 不 管 是 Elasticsearch 集 群 还 是 Logstash 集 群 都 是 可 以 线性 扩展 的 。 


“ 前 端 操 作 炫 丽 。Kibana 界 面 上 ， 只 需 点 击 鼠 标 ， 就 可 以 完成 搜索 、 聚 合 功能 ， 生 成 炫丽 的 仪表 盘 。 


当然 ，ELK stack 并 不 是 实时 数据 分 析 的 灵丹妙药 ， 使 用 不 恰当 ， 会 事倍功半 。 我 自 2014 年 年 初 开 QQ 群 交流 ELK stack， 发 现 网 友 们 对 ELK stack 的 原理 常 有 误解 误 用 ， 对 实现 的 效果 也 多 有 不 能 
解 或 者 因 过 多 期 望 而 失 望 之 处 。 更 令 我 惊奇 的 是 ， 网 友 们 分 布 之 广 ， 遍 及 传统 企业 和 互联 网 公司 、 开 发 和 运 维 领域 、Linux 和 Windows 平 台 ， 大 家 对 非 专 精 领域 的 知识 ， 一 般 都 缺乏 了 解 ， 这 也 成 为 使 用 ELK 
stack 的 一 个 障碍 。 


为 此 ， 我 决定 写 一 本 ELK stack 技 术 指 南 ， 帮 助 大 家 厘清 技术 细节 ， 分 享 一 些 实战 案例 。 本 书 并 不 会 逐一 介绍 ELK stack 的 全 部 聚合 语法 或 者 分 词 特性 ， 而 是 从 日 志 数据 处 理 的 角度 介绍 数据 的 解析 、 导 
入 、 可 视 化 方式 ， 讲 解 集群 的 稳定 性 和 性 能 优化 原理 ， 剖 析 代码 要 点 并 提供 ELK stack 二 次 开发 实例 。 


本 书包 括 三 大 部 分 共 19 章 ， 各 部 分 可 以 独立 阅读 。 但 对 于 还 没有 大 规模 应 用 经 验 的 新 手 ， 建 议 按 顺序 阅读 全 文 。 


第 一 部 分 “Logstash 


第 1 章 : 入 门 示例 。 该 章 介绍 Logstash 及 其 插件 的 配置 安装 方法 ， 自 定义 配置 语言 的 设计 用 途 ， 并 为 不 熟悉 Linux 系 统管 理 的 开发 人 员 介绍 了 多 种 后 台 运 行 方式 。 


第 2 章 : 插件 配置 。 该 章 列举 Logstash 最 常用 的 几 十 种 插件 ， 通 过 实际 示例 和 效果 ， 讲 解 各 插件 的 配置 细节 和 用 途 。 


第 3 章 : 场景 示例 。 该 章 以 最 常见 的 运 维 、 网 络 、 开 发 和 数据 库 场景 ， 介 绍 Logstash 处 理 Nginx、Postfix、Ossec、Log4J、MySQL、Docker 等 日 志 的 最 佳 实践 。 


第 4 章 : 性 能 与 监控 。 了 解 Logstash 的 性 能 情况 一 直 是 个 难题 ， 该 章 从 Logstash 设 计 原 理 和 JVM 平 台 本 质 出 发 ， 介 绍 几 种 行 之 有 效 的 检测 和 监控 方案 。 


第 5 章 : 扩展 方案 。 该 章 介绍 采用 Redis 和 Kafka 完 成 Logstash 水 平 扩展 的 方案 ， 同 时 也 介绍 其 他 几 种 日 志 收 集 系统 与 Logstash 的 配合 方式 。 


第 6 章 : Logstash 源 码 解析 。 该 章 解析 Logstash 源 码 中 最 重要 的 Pipeline 设 计 ， 以 及 Logstash: : Event 的 来 龙 去 脉 。 


第 7 章 : 插件 开发 。 该 章 以 最 常见 的 用 户 登 录 记 录 和 地 址 库 解 析 、Consul 数 据 更 新 等 需求 ， 实 际 演示 Logstash 的 自 定义 Fiter、Input 和 Output 插 件 的 编写 ， 同 时 还 涉及 了 插件 打包 的 RubyGems 规 范 共 
有 HttpClient 功 能 项 等 细节 。 


第 二 部 分 “Elasticsearch 


第 8 章 : 架构 原理 。 该 章 从 更 高 级 的 架构 层面 ， 介 绍 Elasticsearch 分 布 式 设计 中 涉及 稳定 性 和 高 性 能 的 部 分 原理 ， 并 由 此 引发 相关 的 优化 配置 介绍 。 另 外 ， 还 提供 了 一 种 针对 时 序数 据 索引 的 读 写 分 离 方 
案 ， 适 用 于 拥有 少 部 分 SSD 设 备 的 用 户 。 


第 9 章 : 数据 接口 用 例 。 该 章 介绍 Elasticsearch 的 RESTfu| 接 口 的 基础 知识 ， 并 针对 常见 的 重建 索引 需求 提供 两 种 快速 实现 方案 ， 为 有 Spark 经 验 的 读者 介绍 通过 Spark Streaming 接 口 读 写 
Elasticsearch 的 方法 。 


第 10 章 : 性 能 优化 。 该 章 介绍 Elasticsearch 在 日 志 处 理 场景 下 的 读 写 优化 知识 和 官方 推荐 的 curator 工 具 ， 其 中 重点 介绍 了 Elasticsearch 中 几 种 不 同 的 cache 的 区 别 和 有 效 场景 。 


第 11 章 : 测试 和 扩展 方案 。 该 章 介绍 Elasticsearch 在 生产 环境 中 需要 的 一 些 周边 工具 ， 比 如 Puppet 配 置 管理 、Shield 权 限 管理 、 版 本 升级 操作 、 别 名 切换 流程 设计 等 。 


第 12 章 : 映射 与 模板 的 定制 。 该 章 详细 介绍 Elasticsearch 中 的 核心 类 型 及 其 对 应 的 常见 映射 设置 ， 以 及 如 何 通 过 动态 模板 简化 映射 定制 操作 的 复杂 度 。 


第 13 章 : 监控 方案 。Elasticsearch 作 为 一 个 分 布 式 系统 ， 也 是 有 一 定 的 运 维 难 度 的 ， 因 此 其 本 身 的 监控 也 相当 重要 。 该 章 介 绍 Elasticsearch 自 带 的 一 系列 监控 接口 ， 以 及 由 此 衍生 的 多 种 实时 或 长 期 的 
监控 方案 。 


第 14 章 : Elasticsearch 在 运 维 监控 领域 的 其 他 应 用 。 该 章 介 绍 Elasticsearch 在 运 维 方面 的 其 他 运用 方式 ， 包 括 实 时 过 滤 接 口 、 定 时 报警 系统 设计 、 时 序数 据 存储 和 相关 性 排序 等 。 


第 三 部 分 Kibana 


第 15 章 : Kibana 的 产品 对 比 。 该 章 介绍 Kibana 3 与 Kibana 4 之 间 ， 以 及 它们 与 Hadoop、Splunk 之 间 的 差异 ， 方 便 读者 在 不 同 场景 需求 下 选择 更 正确 的 工具 。 


第 16 章 : Kibana 3。 该 章 介绍 Kibana 3 的 界面 操作 方式 、 面 板 的 配置 细节 及 其 效果 、 动 态 仪表 盘 的 高 级 用 法 ， 并 提供 了 几 种 额外 权限 控制 的 部 署 方案 。 


第 17 章 : Kibana 3 源码 解析 。 该 章 以 index.htm| 为 入 口 ， 介 绍 Kibana 3 如 何 利用 angular.js、elastic.js 和 jquery.flot.js 三 大 框架 实现 单 页 应 用 。 重 点 解析 面板 的 实现 过 程 ， 并 分 别 演示 了 采用 facet 和 
agg 接 口 开 发 一 个 Kibana 3 面板 的 过 程 。 


第 18 章 : Kibana 4。 该 章 介绍 Kibana 4 的 安装 部 署 和 界面 操作 方式 ， 重 点 介绍 Kibana 4 提供 的 几 种 可 视 化 图 表 的 配置 细节 和 效果 ， 并 以 几 种 场景 的 日 志 分 析 需 求 演示 了 Kibana 4 全 新 的 子 聚合 功能 的 效 
果 。 最 后 还 介绍 了 一 种 采用 phantom.js 截 图 方式 记录 长 期 报表 数据 的 方案 。 


第 19 章 : Kibana 4 源码 解析 。 该 章 介绍 Kibana 4 的 界面 实现 ， 重 点 包括 其 内 部 ORM 实 现 的 Counrier 类 、 可 视 化 绘图 的 Vislib 类 等 。 
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"第 5 章 扩展 方案 


- 第 6 章 Logstash 源 码 解析 


-BTE ”插件 开发 


国内 的 启蒙 式 分 享 ， 并 主办 Elasticsearch 中 国 用 户 大 会 ， 吴 晓 刚 积极 帮助 新 用 户 ， 并 最 早 分 享 了 携程 的 ELK stack 日 亿 级 规模 的 实例 。 
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Elasticsearch 的 读 写 分 离 和 别名 应 用 章节 。 
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第 一 部 分 “Logstash 


Logstash is a tool for managing events and logs.You can use it to collect logs, parse them, and store them for later use (like, for searching) .--http://logstash.net 


Logstash 项 目 诞 生 于 2009 年 8 月 2 日 。 其 作者 是 世界 著名 的 运 维 工程 师 乔 丹 ， VS XE. (Jordan Sissel) , 4RJb- 西 塞 当时 是 著名 虚拟 主机 托管 商 DreamHiost 的 员工 ， 还 发 布 过 非常 棒 的 软件 打包 工具 fpm， 并 主办 
着 一 年 一 度 的 Sysadmin Advent Calendar (advent calendar 文 化 源 自 基督 教 氛围 浓厚 的 Petd 社 区， 在 每 年 圣诞 来 临 的 12 月 举办 ， 从 12 月 1 日 起 至 12 月 24 日 止 ， 每 天 发 布 一 篇 小 短文 介绍 主题 相关 技术 ) 。 


Logstash 动 手 很 早 ， 对 比 一 下 ，Sctibed 诞 生 于 2008 年 ，Flume 诞 生 于 2010 年 ，Graylog2 诞 生 于 2010 年 ，Fluentd 诞 生 于 2011 年 。Scribed 在 2011 年 进入 半死 不 活 的 状态 ， 大 大 激发 了 其 他 各 种 开源 日 志 收集 处 理 


框架 的 鞍 勃 发 展 ，Logstash 也 从 2011 年 开始 进入 commit 密 集 期 并 延续 至 今 。 


作为 一 个 系 出 名 门 的 产品 ，Logstash 的 身影 多 次 出 现在 Sysadmin Weekly 上 ， 它 和 小 伙伴 们 Elasticsearch、Kibana 直 接 成 为 了 和 商业 产品 Splunk 做 比较 的 开源 项 目 〈 乔 丹 . 西 塞 曾经 在 博客 上 承认 设计 想法 来 
自 AWS 平 台 上 最 大 的 第 三 方 日 志 服 务 商 Loggly， 而 Loggly 两 位 创始 人 都 曾 是 Splunk 员 工 ) 。 


2013 年 ，Logstash 被 Elasticsearch 公 司 收购 ，ELK stack 正 式 成 为 官方 用 语 。Elasticsearch 本 身 也 是 近 两 年 最 受 关注 的 大 数据 项 目 之 一 ， 三 次 融资 已 经 超过 一 亿美 元 。 在 Elasticsearch 开 发 人 员 的 共同 努力 


下 ，Logstash 的 发 布 机制 、 插 件 架 构 也 盒 发 科学 和 合理 。 


社区 文化 


日 志 收 集 处 理 框架 很 多 ， 如 Scribe 是 Facebook 出 品 ，Flume 是 Apache 基 金 会 项 目 ， 都 算 声 名 赫赫 。 但 Logstash 因 乔丹 西 塞 的 个 人 性 格 ， 形 成 了 一 套 独 特 的 社区 文化 。 每 一 个 在 Google Groups 的 Logstash- 


Users 组 里 问答 的 人 都 会 看 到 这 么 一 自 话 : 


Remember: if anew user has a bad time, it’ sa bugin Logstash. 


所 以 ，Logstash 是 一 个 开放 的 、 极 其 互助 和 友好 的 大 家 庭 。 如 有 问题 ， 仅 管 在 Github Issue, Google Groups, Freenode£logstash Channel 上 发 问 就 好 ! 


第 | 章 


入 门 示 例 


什么 是 Logstash? 为 什么 要 用 Logstash? 怎么 用 Logstash? 这 是 本 章 将 要 介绍 的 内 容 。 本 章 从 最 基础 的 知识 着 手 ， 从 以 下 几 步 介绍 Logstash 的 必 备 知识 。1) 下 载 安 装 。 介 绍 Logstash 软 件 的 多 种 安装 
部 署 方 式 ， 并 给 出 推荐 的 方式 。2) 初次 运行 。 通 过 Hello World 示 例 ， 演 示 Logstash 最 简单 的 运用 ， 解 释 其 逻辑 上 的 基础 原理 。3) 配置 语法 。 介 绍 Logstash 的 DSL 设 计 ，Logstash 命 令 的 运行 参数 。4) 
灵活 和 丰富 的 插件 是 Logstash 最 重要 的 优势 。 本 节 会 介绍 Logstash 插 件 的 安装 方式 。5) 长 期 运行 方式 。 从 初次 终端 测试 到 长 期 后 台 稳定 运行 ， 本 节 会 介绍 几 种 不 同方 案 ， 供 读者 根据 实际 场景 


插件 安装 。 
选择 。 


11 下 载 安装 


1. 下 载 


Logstash 从 1.5 版 本 开始 ， 将 核心 代码 和 插件 代码 完全 剥离 ， 并 重 构 了 插件 架构 逻辑 ， 所 有 插件 都 以 标准 的 Ruby Gem 包 形式 发 布 。 不 过 ， 为 了 方便 大 家 从 1.4 版 本 过 渡 ， 目 前 ， 官 方 依 然 发 布 打包 有 所 
有 官方 维护 插件 在 内 的 软件 包 。 只 是 不 再 发 布 类 似 原先 1.4 时 代 的 logstash-contrib.tar.gz 这 样 的 软件 包 了 。 依 然 要 使 用 社区 插件 的 读者 ， 请 阅读 稍 后 1.4 节 “插件 安装 ”。 


下 载 官方 软件 包 的 方式 有 以 下 几 种 : 


“压缩 包 方式 


wget https://download.elastic.co/logstash/logstash/logstash-1.5.1.tar.gz 


: Debian 平台 


wget https://download.elastic.co/logstash/logstash/packages/debian/ 
logstash 1.5.1-1 all.deb 


* Redht 4 4 


wget https: //download.elastic.co/logstash/logstash/packages/centos/ 
logstash-1.5.1-1.noarch.rpm 


2 安装 


在 上 面 这 些 包 中 ， 你 可 能 更 偏向 使 用 rpm、dpkg 等 软件 包 管理 工具 来 安装 Logstash， 开 发 者 在 软件 包 里 预定 义 了 一 些 依赖 。 比 如 ，logstash-1.5.1-1.narch 就 依赖 于 jre 包 。 


另外 ， 软 件 包 里 还 包含 有 一 些 很 有 用 的 脚本 程序 ， 比 如 /etc/init.d/logstash。 


如 果 你 必须 在 一 些 很 老 的 操作 系统 上 运行 Logstash， 那 你 只 能 用 源 代码 包 部 署 了 ， 记 住 要 自己 提前 安装 好 Java: 


yum install openjdk-jre 
export JAVA HOME=/usr/java 
tar zxvf logstash-1.5.1.tar.gz 


3. 最 佳 实践 


但 是 真正 的 建议 是 : 如 果 可 以 ， 请 用 Elasticsearch 官 方 仓库 来 直接 安装 Logstash1! 


: Debian 平 台 


wget -0 - http://packages.elasticsearch.org/GPG-KEY-elasticsearch | apt-key add - 
cat »» /etc/apt/sources.list ««EOF 

deb http://packages.elasticsearch.org/logstash/1.5/debian stable main 

EOF 

apt-get update 

apt-get install logstash 


:Redhat 平台 


rpm --import http://packages.elasticsearch.org/GPG-KEY-elasticsearch 
cat » /etc/yum.repos.d/logstash.repo ««EOF 

[1ogstash-1.5] 

name-logstash repository for 1.5.x packages 
baseurl-http://packages.elasticsearch.org/logstash/1l.5/centos 
gpgcheck-1 

gpgkey-http: / /packages .elasticsearch.org/GPG-KEY-elasticsearch 
enabled-l 

EOF 

yum clean all 

yum install logstash 


1.2 Hello World 


与 绝 大 多 数 IT 技 术 介绍 一 样 ， 我 们 也 以 一 个 输出 “Hello World” 的 形式 开始 学 习 Logstash。 


在 终端 中 ， 像 下 面 这 样 运行 命令 来 启动 Logstash 进 程 : 


# bin/logstash -e 'input{stdin{}}output {stdout (codec-»rubydebug)]"' 


AEREA RESA. imm, AA Hello World， 回 车 ， 看 看 会 返回 什么 结果 ! 


{ “message” => “Hello World” , “@version” => “1” , "Gtimestamp' =>“2014-08-07T10:30:59.9372”，“host” => "raochenlindeMacBook-Air.local" , 
} 


没 错 ! 就 是 这 么 简单 。 


2. 完 整 示例 


命令 行 运行 当然 不 是 什么 特别 方便 的 用 法 ， 所 以 绝 大 多 数 情况 下 ， 我 们 都 是 采用 额外 定义 一 个 logstash.conf 配 置 文件 的 方式 来 启动 Logstash。 下 面 是 我 们 的 第 一 个 完整 版 logstash.conf 的 示例 : 


input { 
stdin ( } 
l 
output ( 
stdout ( 
codec => rubydebug {} 
$ 
elasticsearch { 
embedded => true 
l 
} 


然后 在 终端 上 这 样 运行 : 


# bin/logstash -f logstash.conf 


同样 ， 还 是 输入 一 次 Hello World。 你 会 看 到 和 上 一 次 一 样 的 一 段 Ruby 对 象 输出 。 但 事实 上 ， 这 个 完整 示例 可 不 止 如 此 。 打 开 另 一 个 终端 ， 输 入 下 面 一 行 命令 : 


# curl http://127.0.0.1:9200/ search?q-hello 


你 会 看 到 终端 上 输出 下 面 这 么 一 段 内 容 : 


{ "took" :15, "timed out" :false, " shards" :( “total” :27, “successful” :27, "failed" :0), "hits" :( "total" :1, "max score" :0.095891505, "hits" :[( ”index”:“1logstash-2015.08.22 


如 果 你 使 用 的 是 Logstash-1.5 以 下 的 版 本 ， 你 还 可 以 直接 通过 bin/logstash web 命 令 ， 启 动 Kibana 应 用 ， 然 后 在 浏览 器 上 访问 http://127.0.0.1: 9292/ 地 址 ， 可 以 看 到 如 图 1-1 所 示 的 效果 。 我 们 在 终 
端 上 输入 的 数据 ， 就 可 以 从 页 面 上 任意 搜索 了 。 


Q f |D 127.0.0.1:92924ndex.htmiti/deshboerdi/ile/iogstash.json 
-ai Logstash Search a day ago 10 a few seconds ago * 


QUERY » 


9 hello 


Vew» | & Zcom Out| ® hello|!] count per 10m | (15115) 
12 


10 


o8 


06 


04 


02 


Fields O 0 to 1 of ! avaiable for paging 


Ad (165 / Current (7) .source (select cotumns from the Bst to tne left) 
Typo to fiter... (' message" "Hello Word "Overnson":*1* "trtmestemo:*2015-08-21705:38:53, 3867" "host" ^ranchaniindeMacfoo k-Air oca] 


Oto 1 of 1 avaiable for pagng 


1-1 Kibana 上 搜索 的 hello world 


如 果 你 使 用 的 是 Logstash-1.5 以 上 版 本 ，Logstash 已 经 不 再 自 带 Kibana 代 码 ， 你 就 只 能 自己 安装 部 署 一 套 Kibana 程 序 了 ， 相 关内 容 ， 可 以 稍 后 阅读 本 书 第 三 部 分 的 介绍 。 


3. 解 释 


每 位 系统 管理 员 都 肯定 写 过 很 多 类 似 这 样 的 命令 : cat randdata|awk (print$2)'|sort|uniq-c|tee sortdata。 这 个 管道 符 | 可 以 算是 Linux 世 界 最 伟大 的 发 明之 一 ( 另 一 个 是 “一 切 皆 文 件 ”) 。 


Logstash 就 像 管道 符 一 样 ! 


你 输入 (就 像 命 令 行 的 cat) 数据 ， 然 后 处 理 过 滤 | (就 像 awk 或 者 uniq 之 类 ) 数据 ， 最 后 输出 (就 像 tee) 到 其 他 地 方 。 


当然 实际 上 ，Logstash 是 用 不 同 的 线程 来 实现 这 些 的。 如 果 你 运行 top 命 令 然后 按 下 H 键 ， 你 就 可 以 看 到 下 面 这 样 的 输出 : 


PID USER PR NI VIRT RES SHR S $CPU $MEM TIME- COMMAND 
21401 root 16 0 1249m 303m 10m S 18.6 0.2 866:25.46 |worker 
21467 root 15 0 1249m 303m 10m S 3.7 0.2 129:25.59 »elasticsearch. 
21468 root 15 0 1249m 303m 10m S 3.7 0.2 128:53.39 »elasticsearch. 
21400 root 15 0 1249m 303m 10m S 2.7 0.2 108:35.80 «f?ile 
21403 root 15 0 1249m 303m 10m S 1.3 0.2 49:31.89 »output 
21470 root 15 0 1249m 303m 10m S 1.0 0.2 56:24.24 »elasticsearch. 


如 上 例 所 示 ，Logstash 很 温馨 地 给 每 类 线程 都 取 了 名 字 ， 输 入 的 叫 <xx， 过 滤 的 叫 |xx， 输 出 的 叫 >xx。 


数据 在 线程 之 间 以 事件 的 形式 流传 。 不 要 叫 行 ， 因 为 Logstash 可 以 处 理 多 行事 件 。 


Logstash 会 给 事件 添加 一 些 额 外 信息 。 最 重要 的 就 是 @timestamp， 用 来 标记 事件 的 发 生 时 间 。 因 为 这 个 字段 涉及 Logstash 的 内 部 流转 ， 所 以 必须 是 一 个 joda 对 象 ， 如 果 你 尝试 自己 给 一 个 字符 串 字 段 
命名 为 @timestamp 的 话 ，Logstash 会 直接 报错 。 所 以 ， 请 使 用 logstash-filter-date 插 件 来 管理 这 个 特殊 字段 。 


中 


此 外 ， 大 多 数 时 候 ， 还 可 以 见 到 另外 几 个 : 


. host 标 记事 件 发 生 在 哪里 。 
type 标记 事件 的 唯一 类 型 。 


“ tags 标 记事 件 的 菜 方 面 属性 。 这 是 一 个 数组 ， 一 个 事件 可 以 有 多 个 标签 。 


你 可 以 随意 给 事件 添加 字段 或 者 从 事件 里 删除 字段 。 事 实 上 事件 就 是 一 个 Ruby 对 象 ， 或 者 更 简单 地 理解 为 就 是 一 个 哈 希 也 行 。 


每 个 Logstash 过 滤 插 件 ， 都 会 有 四 个 方法 叫 add tag. remove tag, add field 和 remove field， 它 们 在 插件 过 滤 匹配 成 功 时 生效 。 


推荐 阅读 
- 官网 上 “the life of an event” 文 档 : http://logstash.net/docs/1.4.2/life-of-an-event 


* Elastic{ON} 上 《life of alogstash event》 演 讲 : https:/ /speakerdeck.com/elastic/life-of-a-logstash-event 
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Logstash 社 区 通常 习惯 用 Shipper、Broker 和 Indexer 来 描述 数据 流 中 不 同 进程 各 自 的 角色 。 如 图 1-2 所 示 。 


Search & 
Storage 


ElasticSearch 
10.0.0.1 


图 1-2 Logstash 角 色 说 明 


不 过 我 见 过 很 多 运用 场景 里 都 没有 用 Logstash 作 为 Shipper， 或 者 说 没有 用 Elasticsearch 作 为 数据 存储 ， 也 就 是 说 也 没有 Indexer。 所 以 ， 我 们 其 实 不 需要 这 些 概 念 。 只 需要 学 好 怎么 使 用 和 配置 
Logstash 进 程 ， 然 后 把 它 运用 到 你 的 日 志 管理 架构 中 最 合适 它 的 位 置 就 够 了 。 


1.3.1 语法 


Logstash 设 计 了 自己 的 DSL 一 一 有 点 像 Puppet 的 DSL， 或 许 因为 都 是 用 Ruby 语 言 写 的 吧 一 一 包括 区 域 、 注 释 、 数 据 类 型 (布尔 值 、 字 符 串 数值 、 数 组 、 哈 希 ) ， 条 件 判断 、 字 段 引用 等 。 


1. 区 段 (section) 


Logstash 用 人 } 来 定义 区 域 。 区 域内 可 以 包括 插件 区 域 定义 ， 你 可 以 在 一 个 区 域内 定义 多 个 插件 。 揪 件 区 域内 则 可 以 定义 键 值 对 设置 。 示 例如 下 : 


input { 
stdin {} 
syslog {} 


2 数据 类 型 
Logstash 支 持 少量 的 数据 值 类 型 ; 


- 希 尔 值 (bool) 


debug => true 


字符 串 (string) 


host => "hostname" 


数值 (number) 


port => 514 


数组 (array) 


match => [ “datetime” , “UNIX” , “IS08601” ] 


哈 希 (hash) 


options => ( 


keyl => "valuel' , 
key2 => "value2" 


} 


如 果 你 用 的 版 本 低 于 1.2.0， 哈 希 的 语法 跟 数 组 是 一 样 的 ， 像 下 面 这 样 写 : 


match => [ “f?ieldl” , "patternl' , "f?ield2' , “pattern2” ] 


3. 字 段 引 用 (field reference) 


字段 是 Logstash : 


如 果 你 想 在 Logstash 配 置 中 使 有 


VF REFR" 
这 个 数据 的 ) : 


: Event 对 象 的 属性 。 我 们 之 前 提 过 事件 就 像 一 个 哈 希 一 样 ， 所 以 你 可 以 想象 字段 就 像 一 个 键 值 对 。 


字段 的 值 ， 只 需 把 字段 的 名 字 写 在 中 括号 [里 就 行 了 ， 这 就 叫 “ 字 段 引 


(也 就 是 多 维 哈 希 表 ， 或 者 叫 哈 希 的 哈 希 ) ， 每 层 的 字段 名 都 写 在 [里 就 可 以 了 。 


比如 ， 你 可 以 从 geoip 里 这 样 获取 longitude 值 (是 的 ， 这 是 个 笨 办 法 ， 实 际 上 有 单独 的 字段 专门 存 


[geoip] [location] [0] 


小 知识 


Logstash 的 数组 也 支持 倒序 下 标 ， 即 [geoipj[location][1] 可 以 获取 数组 最 后 一 个 元 素 的 值 。 


Logstash 还 支持 变量 内 插 ， 在 字符 串 里 使 用 字段 引用 的 方法 是 这 样 : 


"the longitude is %{[geoip] [location] [0 


4. 条 件 判 断 (condition) 


Logstash 从 1.3.0 版 开始 支持 条 件 判断 和 表达 式 。 


表达 式 支持 下 面 这 些 操作 符 : 
'equality, etc: ==, !2, €, >, <=, >= 
"regexp: =~, !~ 


"inclusion: in, not in 
"boolean: and, or, nand, xor 


"unary: ! () 


通常 来 说 ， 你 都 会 在 表达 式 里 用 到 字段 引用 。 比 如 : 


if ^" grokparsefailure” not in [tags] ( 
) else if [status] !~ /^2\d\d/ and [url] ==  "/noc.gif" { 


) else ( 


Logstash 提 供 了 一 个 shell 脚 本 叫 logstash 方 便 快 速 运行 ， 下 面 介 绍 它 支持 的 参数 : 


1.-e 


意 即 “执行 ”。 我 们 在 


"Hello World” 的 时 候 已 经 用 过 这 个 参数 了 。 事 实 上 你 可 以 不 写 任何 具体 配置 ， 直 接 运行 bin/logstash-e'" 可 达到 相同 效果 。 这 个 参数 的 默认 值 是 下 面 这 样 : 


input 1{ 
stdin { } 
} 
output { 
stdout { } 
} 


2.--config 或 -f 


意 即 “文件 ”。 真 实 运 


此 外 ，Logstash 还 提供 一 个 方便 我 们 规划 和 书写 配置 的 小 功能 。 你 可 以 直接 


里 拼接 成 一 个 完整 的 大 配置 文件 ， 再 去 执行 。 


3.--configtest 或 -t 


bin/logstash-f/etc/logstash.d/ 来 运行 。Logstash 会 


意 即 “测试 ”。 


来 测试 Logstash 读 取 到 的 配置 文件 语法 是 否 能 正常 解析 。Logstash 配 置 语法 是 


中 ， 我 们 会 写 很 长 的 配置 ， 甚 至 可 能 超过 shell 所 能 支持 的 1024 个 字符 长 度 。 所 以 我 们 必 把 配置 固化 到 文件 里 ， 然 后 通过 bin/logstash-fagent.conf 这 样 的 形式 来 运行 。 


自动 读 取 /etc/logstash.d/ 目 录 下 所 有 的 文本 文件 ， 然 后 在 自己 内 存 


grammar.treetop 定 义 的 。 尤 其 是 使 


了 上 一 条 提 到 的 读 取 目录 方式 的 读者 ， 尤 其 要 提前 测试 。 


4.--log 或 -| 


意 即 “日 志 ”。Logstash 默 认输 出 日 志 到 标准 错误 。 生 产 环境 下 你 可 以 通过 bin/logstash-| logs/logstash.log 命 令 来 统一 存储 日 志 。 


5.--filterworkers 或 -w 


意 即 “工作 线程 ”。Logstash 会 运行 多 个 线程 。 你 可 以 用 bin/logstash-w 5 这 样 的 方式 强制 Logstash 为 “过 滤 插件 ” (Logstash 目 前 还 不 支持 输入 插件 的 多 线程 ， 输 出 插件 的 多 线程 则 是 在 配置 内 设 
B) 运行 5 个 线程 。 


o 
nd 
Dy 


Logstash 目 前 不 支持 对 过 滤器 线程 的 监测 管理 。 如 果 filterworker 挂 掉 ，Logstash 会 处 于 一 个 无 flter 的 僵 死 状态 。 这 种 情况 在 使 用 flter/ruby 自 己 写 代码 时 非常 需要 ， 很 容易 碰 上 NoMethodError: undefined 


method'*'for nil: NilClass 错 误 。 需 要 妥善 处 理 ， 提 前 判断 。 


6.--pluginpath 或 -P 


可 以 写 自 己 的 插件 ， 然 后 用 bin/logstash--pluginpath/path/to/own/plugins 加 载 它们 。 
Qus 


如 果 你 使 用 的 Logstash 版 本 在 1.5.0-rc3 到 1.5.3 之 间 ， 该 参数 一 度 被 取消 ， 请 阅读 本 书 稍 后 插件 开发 章节 ， 改 用 本 地 gem 插 件 安装 形式 。 


i 


7.--verbose 


输出 一 定 的 调试 日 志 。 如 果 你 使 用 的 Logstash 版 本 低 于 1.3.0， 则 用 bin/logstash-v 来 代替 。 


8.--debug 


输出 更 多 的 调 斌 日志。 如 果 你 使 用 的 Logstash 版 本 低 于 1.3.0， 则 用 bin/logstash-vv 来 代替 。 
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从 Logstash 1.5.0 版 本 开始 ，Logstash 将 所 有 的 插件 都 独立 拆 分 成 gem 包 。 这 样 ， 每 个 插件 都 可 以 独立 更 新 ， 不 用 等 待 Logstash 自 身 做 整体 更 新 的 时 候 才能 使 用 了 。 


为 了 达到 这 个 目标 ，Logstash 配 置 了 专门 的 plugin 管 理 命令 。 


plugin 命 令 用 法 说 明 如 下 : 


Usage: 

bin/plugin [OPTIONS] SUBCOMMAND [ARG] … 
Parameters: 

SUBCOMMAND subcommand 

[ARG] … subcommand arguments 
Subcommands : 

install Install a plugin 

uninstall Uninstall a plugin 

update Install a plugin 

list List all installed plugins 
Options: 

-h, --help print help 


首先 ， 你 可 以 通过 bin/plugin list 查 看 本 机 现在 有 多 少 插件 可 用 。 (其 实 就 在 vendor/bundle/jruby/1.9/gems/ 目 录 下 。) 


ki 


然后 ， 假 如 你 看 到 https://github.com/logstash-plugins/ 下 新 发 布 了 一 个 logstash-output-webhdfs 模 块 (当然 目前 还 没有 ) 。 打 算 试 试 ， 就 只 需 运 行 如 下 命 


bin/plugin install logstash-output-webhdfs 


同样 ， 假 如 是 升级 ， 只 需 运 行 如 下 命令 即 可 : 


bin/plugin update logstash-input-tcp 


bin/plugin 不 但 可 以 通过 rubygems 平 台 安装 插件 ， 还 可 以 读 取 本 地 路 径 的 gem 文 件 ， 这 对 自 定义 插件 或 者 无 外 接 网 络 的 环境 都 非常 有 效 : 


bin/plugin install /path/to/logstash-f?ilter-crash.gem 


执行 成 功 以 后 。 你 会 发 现 ，logstash-1.5.0 目 录 下 的 Gemfile 文 件 最 后 会 多 出 一 段 内 容 : 


gem “logstash-f?ilter-crash” , “1.1.0” , :path => "vendor/local gems/d354312c/ 
logstash-f?ilter-mweibocrash-1.1.0” 


同时 Gemfilejruby-1.9.lock 文 件 开头 也 会 多 出 一 段 内 容 ， 如 下 所 示 : 


PATH 
remote: vendor/local gems/d354312c/logstash-f?ilter-crash-1.1.0 
specs: 
logstash-f?ilter-crash (1.1.0) 
logstash-core (>= 1.4.0, < 2.0.0) 
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Oez 


本 章节 问题 对 于 一 个 运 维 来 说 应 该 属于 基础 知识 ， 鉴 于 ELK 用 户 很 多 其 实 不 是 运 维 ， 添 加 这 段 内 容 。 


办 法 有 很 多 种 ， 下 面 介绍 四 种 最 常用 的 办 法 。 


1. 标 准 的 service 方 式 


采用 RPM、DEB 发 行 包 安 装 的 读者 ， 推 荐 采用 这 种 方式 。 发 行 包 内 ， 都 自 带 有 sysV 或 者 systemd 风 格 的 启动 程序 /配置 ， 你 只 需 


载 /etc/init.d/functions 库 文件 ， 利 用 其 中 的 daemon 函 数 ， 将 Logstash 进 程 作为 后 台 程 序 运 行 。 


所 以 ， 你 只 需 把 自己 写 好 的 配置 文件 统一 放 在 /etc/logstash/ 目 录 下 (注意 目录 下 所 有 配置 文件 都 应 该 是 .conf 结 尾 ， 且 不 能 


的 ) ， 然 后 运行 service logstash start 命 令 即 可 。 


2. 最 基础 的 nohup 方 式 


这 是 最 简单 的 方式 ， 也 是 Linux 新 手 们 很 容易 搞 混淆 的 一 个 经 典 问题 : 


其 他 文本 文件 存在 ， 因 


要 直接 使 用 即 可 。 以 RPM 为 例 ，/etcinit.dylogstash 脚 本 中 ,会 加 


为 logstash agent 启 动 的 时 候 是 读 取 全 文件 夹 


command 

command » /dev/null 
command > /dev/null 2»&1 
command & 

command » /dev/null & 
command > /dev/null 2>&1 & 
command &» /dev/null 
nohup command &» /dev/null 


请 回答 以 上 命令 的 异同 .…… 


具体 不 一 一 解释 了 。 直 接 说 答案 ， 想 要 维持 一 个 长 期 后 台 运 行 的 Logstash， 你 需要 同时 在 命令 前 面 加 nohup， 后 面 加 &。 


3. 更 优雅 的 screen 方 式 


screen 算 是 Linux 运 维 一 个 中 高 级 技巧 。 通 过 screen 命 令 创建 的 环境 下 运行 的 终端 命令 ,其 父 进程 不 是 sshd 登 录 会 话 ， 而 是 screen。 这 样 就 可 以 既 避 免 


终端 继续 操作 。 


创建 独立 的 screen 命 令 如 下 : 


户 退 出 进程 消失 的 问题 ， 又 随时 能 重新 接管 


回 


Screen -dmS elkscreen 1 


连接 进入 已 创建 的 elkscreen_1 的 命令 如 下 : 


Screen -r elkscreen 1 


然后 你 可 以 看 到 一 个 一 模 一 样 的 终端 ， 运 行 Logstash 之 后 ， 不 要 按 Ctrl+C， 而 是 按 Ctrl+A+ D 键 ， 断 开 环境 。 想 重新 接管 ， 依 然 


如 果 创 建 了 多 个 screen， 查 看 列表 命令 如 下 : 


screen-r elkscreen_1 即 可 。 


Screen -list 


4. 最 推荐 的 daemontools 方 式 


不 管 是 nohup 还 是 screen， 都 不 是 可 以 很 方便 管理 的 方式 ， 在 运 维 管理 一 个 ELK 集 群 的 时 候 ， 必 须 寻 找 一 种 尽 可 能 简洁 的 办 法 。 所 以 ， 对 于 需要 长 期 后 台 运 行 的 大 量程 序 (注意 大 量 ， 如 果 就 一 个 进 


还 是 学 习 一 下 怎么 写 init 脚 本 吧 ) ， 推 荐 大 家 使 用 一 款 daemontools 工 具 。 


daemontools 是 一 个 软件 名 称 ， 不 过 配置 略 复杂 。 所 以 这 里 我 其 实 是 用 其 名 称 来 指 代 整 个 同类 产品 ， 包 括 但 不 限于 Python 实现 的 supervisord，Perl 实 现 的 ubic，Ruby 实 现 的 god 等 。 


以 supervisord 为 例 ， 因 为 这 个 出 来 得 比较 早 ， 可 以 直接 通过 EPEL 仓 库 安装 。 


yum -y install supervisord --enablerepo-epel 


在 /etc/supervisord.conf 配 置 文件 里 添加 内 容 ， 定 义 你 要 启动 的 程序 ， 如 下 所 示 : 


[program:elkpro 1] 

environment-LS HEAP SIZE-5000m 

directory-/opt/logstash 

command-/opt/logstash/bin/logstash -f /etc/logstash/prol.conf -w 10 -1 /var/ 
log/logstash/prol.log 

[program:elkpro 2] 

environment-LS HEAP SIZE-5000m 

directory-/opt/logstash 

command-/opt/logstash/bin/logstash -f /etc/logstash/pro2.conf -w 10 -1 /var/ 
log/logstash/pro2.1og 


然后 启动 service supervisord start 即 可 。 


Logstash 会 以 supervisord 子 进程 的 身份 运行 ， 你 还 可 以 使 用 supervisorctl 命 令 ， 单 独 控制 一 系列 Logstash 子 进程 中 某 一 个 进程 的 启 停 操作 : 


supervisorctl stop elkpro 2 


第 2 章 插件 配置 


插件 是 Logstash 最 大 的 特色 。 各 种 不 同 的 插件 源源 不 断 地 被 创造 出 来 ， 发 布 到 社区 中 供 大 家 使 用 。 本 章 会 按照 插件 的 类 别 ， 对 一 般 场景 下 的 一 些 常 F 


例 介绍 。 本 章 介绍 的 插件 包 


插件 做 详细 的 配置 和 上 


$5: 1) 输入 插件 。 基 于 shipper 端 场景 ， 主 要 介绍 STDIN、TCP、File 等 插件 。2) 编 解码 插件 。 编 解码 通常 是 会 被 遗忘 的 环节 ， 但 是 运用 好 了 ， 会 大 大 提高 工作 效率 ， 本 节 介绍 最 常用 的 JSJON 和 multiline 
插件 。3) 过 滤器 插件 。 名 为 过 滤器 ， 其 实 各 种 数据 裁剪 和 计算 都 可 以 在 这 类 插件 里 完成 ， 是 Logstash 最 强大 的 一 环 。 本 节 会 详细 介绍 grok、date、mutate、ruby、metrics 等 插件 的 妙用 。4) 输出 插件 。 
Logstash 昌 然 经 常 跟 Elasticsearch 并 称 ， 但 是 作为 一 个 日 志 传 输 框架 ， 它 其 实 可 以 输出 数据 到 各 种 不 同 的 地 方 。 比 如 Graphite、HDFS、Nagios 等 等 。 本 节 会 介绍 这 些 常用 的 输出 插件 用 法 。 


2.1 输入 插件 


Æ “Hello World” 示 例 中 ， 我们 已 经 见 到 并 介绍 了 Logstash 的 运行 流程 和 配置 的 基础 语法 。 从 这 章 开始 ， 我 们 就 要 逐一 介绍 Logstash 流 程 中 比较 常用 的 一 些 插件 ， 并 在 介绍 中 针对 其 主要 适用 的 场 
景 、 推 荐 的 配置 ， 作 一 些 说 明 。 


限于 篇 幅 ， 接 下 来 内 容 中 ， 配 置 示例 不 一 定 能 贴 完整 。 请 记 住 一 个 原则 : Logstash 配 置 一 定 要 有 一 个 input 和 一 个 output。 在 演示 过 程 中 ， 如 果 没 有 写 明 input， 默 认 就 会 使 用 “Hello World” 里 我 们 
已 经 演示 过 的 logstash-input-stdin， 同 理 ， 没 有 写 明 的 output 就 是 logstash-output-stdout。 


以 上 请 读者 自明 。 


2.1.1 标准 输入 


我 们 已 经 见 过 好 几 个 示例 使 用 stdin 了 。 这 也 应 该 是 Logstash 里 最 简单 和 基础 的 插件 了 。 所 以 ， 在 这 段 中 ， 我 们 先 介绍 一 些 未 来 每 个 插件 都 会 有 的 一 些 方法 。 


配置 示例 如 下 : 


input { 
stdin { 
add field => { "key' => "value" } 


tags => [ “add” ] 
type => "std" 
} 


上 面 的 新 stdin 设 置 重新 运行 一 次 最 开始 的 Hello World 示 例 。 我 建议 大 家 把 整 段 配置 都 写 入 一 个 文本 文件 ， 然 后 运行 命令 : bin/logstash-f stdin.conf, $A "Hello World” 并 回 车 后 ， 你 会 在 终端 
看 到 如 下 输出 : 


{ “message” => “hello world” , “@version” => "1" , "Gtimestamp' => '2014-08-08T06:48:47.7892" , "type" => “std” , "tags" => [ 
[0] “add” 
], “key” => “value” , “host” => “raochenlindeMacBook-Air.local” 


} 


type 和 tags 是 Logstash 事 件 中 两 个 特殊 的 字段 。 通 常 来 说 ， 我 们 会 在 “输入 区 段 ”中 通过 type 来 标记 事件 类 型 一 一 我 们 肯定 是 提前 能 知道 这 个 事件 属于 什么 类 型 的 。 而 tags 则 是 在 数据 处 理 过 程 中 ， 
具体 的 插件 来 添加 或 者 删除 的 。 


最 常见 的 用 法 是 像 下 面 这 样 : 


type — "web" 


} 
filter { 
if [type] == “web” { 
grok { 
match => [ “message” , %{COMBINEDAPACHELOG}] 
} 
} 
} 
output { 
if “_grokparsefailure” in [tags] { 


nagios_nsca { 
nagios_status => “1” 
} 
} else { 
elasticsearch { 
} 
l 


看 起 来 蛮 复 杂 的 ， 对 吧 ? 


继续 学 习 ， 你 也 可 以 写 出 来 的 。 


2.1.2 文件 输入 


分 析 网 站 访问 日 志 应 该 是 一 个 运 维 工程 师 最 常见 的 工作 了 。 所 以 我 们 先 学 习 一 下 怎么 用 Logstash 来 处 理 日 志文 件 。 


Logstash 使 用 一 个 名 叫 FileWatch 的 Ruby Gem 库 来 监听 文件 变化 。 这 个 库 支持 glob 展 开 文件 路 径 ， 而 且 会 记录 一 个 叫 .sincedb 的 数据 库 文件 来 跟踪 被 监听 日 志文 件 的 当前 读 取 位 置 。 所 以 ， 不 要 担心 
Logstash 会 漏 过 你 的 数据 。 


Qs 


sincedb 文 件 中 记录 了 每 个 被 监听 的 文件 的 inode，major number, minor number 和 pos。 


配置 示例 如 下 : 


input { 
file { 
path => [ "/var/log/*.log' , “/var/log/message” ] 
type => "system" 
start position —» "beginning" 


} 


有 一 些 比较 有 用 的 配置 项 ， 可 以 用 来 指定 FileWatch 库 的 行为 : 


“ discover interval: Logstash 每 隔 多 久 去 检查 一 次 被 监听 的 path 下 是 否 有 新 文件 ， 上 默认 值 是 15 秒 。 

- exclude: 不 想 被 监听 的 文件 可 以 排除 出 去 ， 这 里 跟 path 一 样 支持 glob 展 开 。 

*sincedb path: 如 果 你 不 想 用 默认 的 $HOME/.sincedb (Windows 平 台 上 为 WUSERPROFILE%\.sincedb， 该 变量 默认 值 是 : C: \Windows\System32\config\systemprofile) ， 可 以 通过 这 个 配置 定义 sincedb 
文件 到 其 他 位 置 。 

“sincedb_write_interval: Logstash 每 隔 多 久 写 一 次 sincedb 文 件 ， 默 认 是 15 秒 。 

* stat interval: Logstash 每 隔 多 久 检 查 一 次 被 监听 文件 状态 (是否 有 更 新 ) ， 默 认 是 1 秒 。 


“start_position: Logstash 从 什么 位 置 开始 读 取 文 件数 据 ， 默 认 是 结束 位 置 ， 也 就 是 说 ，Logstash 进 程 会 以 类 似 tail-F 的 形式 运行 。 如 果 你 是 要 导入 原 有 数据 ， 把 这 个 设 定 改 成 "beginning"，Logstash 进 程 就 从 


头 开始 读 取 ， 有 点 类 似 于 cat， 但 是 读 到 最 后 一 行 不 会 终止 ， 而 是 继续 变 成 tail-F。 


注意 事项 如 下 : 


1) 通常 你 要 导入 原 有 数据 进 Elasticsearch 的 话 ， 你 还 需要 filter/date 揪 件 来 修改 默认 的 "@timestamp "字段 值 。 稍 后 会 学 习 这 方面 的 知识 。 


2) FileWatch 只 支持 文件 的 绝对 路 径 ， 而 且 会 不 自动 递归 目录 。 所 以 有 需要 的 话 ， 请 用 数组 方式 都 写 明 具体 哪些 文件 。 


3) LogStash: : Inputs: : File 只 是 在 进程 运行 的 注册 阶段 初始 化 一 个 FileWatch 对 象 。 所 以 它 不 能 支持 类 似 fluentd 那 样 的 path=>"/path/to/%{+yyyy/MM/dd/hh}.log" 写 法 。 达 到 相同 目的 ， 你 只 
能 写成 path=>"/path/to/*/*/*/*.log"。FileWatch 模 块 提供 了 一 个 稍微 简单 一 点 的 写法 : /path/to/**/*.log， 用 * 来 缩写 表示 递归 全 部 子 目 录 。 


4) start_position 仅 在 该 文件 从 未 被 监听 过 的 时 候 起 作用 。 如 果 sincedb 文 件 中 已 经 有 这 个 文件 的 inode 记 录 了 ， 那 么 Logstash 依 然 会 从 记录 过 的 pos 开 始 读 取 数 据 。 所 以 重复 测试 的 时 候 每 回 需要 删除 


sincedb 文 件 。 


5) 因为 Windows 平 台 上 没有 inode 的 概念 ，Logstash 某 些 版 本 在 Windows 平 台 上 监听 文件 不 是 很 靠 谱 。Windows 平 台 上 ， 推 荐 考虑 使 用 nxlog 作 为 收集 端 ， 参 阅 本 书 稍 后 章节 。 


2.1.3 TCP 输 入 


未 来 你 可 能 会 用 Redis 服 务 器 或 者 其 他 的 消息 队列 系统 来 作为 Logstash Broker 的 角色 。 不 过 Logstash 其 实 也 有 自己 的 TCP/UDP 插 件 ， 在 临时 任务 的 时 候 ， 也 算 能 用 ， 尤 其 是 测试 环境 。 


Qus 


虽然 LogStash: : Inputs: : TCP 用 Ruby 的 Socket 和 OpenSSL 库 实现 了 高 级 的 SSL 功 能 ， 但 Logstash 本 身 只 能 在 SizedQueue 中 缓存 20 个 事件 。 这 就 是 我 们 建议 在 生产 环境 中 换 用 其 他 消息 队列 的 原因 。 


配置 示例 如 下 : 


input ( 
tcp ( 
port => 8888 
mode => "server" 
Ssl enable => false 


目前 来 看 ，Logstash: : Inputs: : TCP 最 常见 的 用 法 就 是 配合 nc 命令 导入 旧 数 据 。 在 启动 Logstash 进 程 后 ， 在 另 一 个 终端 运行 如 下 命令 即 可 导入 数据 : 


# nc 127.0.0.1 8888 < olddata 


这 种 做 法 比 用 LogStash: : Inputs: : File 好 ， 因 为 当 nc 命令 结束 ， 我 们 就 知道 数据 导入 完毕 了 。 而 用 input/file 方 式 ，Logstash 进 程 还 会 一 直 等 待 新 数据 输入 被 监听 的 文件 ， 不 能 直接 看 出 是 否 任务 完 


成 了 。 


2.14 syslog 输入 


syslog 可 能 是 运 维 领域 最 流行 的 数据 传输 协议 了 。 当 你 想 从 设备 上 收集 系统 日 志 的 时 候 ，syslog 应 该 会 是 你 的 第 一 选择 。 尤 其 是 网 络 设备 ， 比 如 思科 中 syslog 几 乎 是 唯一 可 行 的 办 法 。 


我 们 这 里 不 解释 如 何 配置 你 的 syslog.conf、rsyslog.conf 或 者 syslog-ng.conf 来 发 送 数据 ， 而 只 讲 如 何 把 Logstash 配 置 成 一 个 syslog 服 务 器 来 接收 数据 。 


有 关 rsyslog 的 用 法 ， 稍 后 的 类 型 项 目 一 节 中 ， 会 有 更 详细 的 介绍 。 


配置 示例 如 下 : 


input { 
syslog { 
port => “514” 
$ 
} 


di 


作为 最 简单 的 测试 ， 我 们 先 暂 停 一 下 本 机 的 syslogd (或 rsyslogd) 进程 ， 然 后 启动 Logstash 进 程 (这 样 就 不 会 有 端口 冲突 问题 ) 。 现 在 ， 本 机 的 syslog 就 会 默认 发 送 到 Logstash 里 了 。 我 们 可 以 上 
的 logger 命 令 行 工具 发 送 一 条 “Hello World" 信息 到 syslog 里 (BPLogstash¥) 。 看 到 的 Logstash 输 出 像 下 面 这 样 : 


{ “message” => “Hello World” , “@version” => “1” , "Gtimestamp' => "2014-08-08T09:01:15.911Z" , "host" => “127.0.0.1” , “priority” -»31, “timestamp” => "Aug 8 17:01:15" , "loc 


} 


Logstash 配 置 实现 一 样 的 效果 ， 如 下 所 示 : 


Logstash 是 用 UDPSocket、TCPServer 和 LogStash: : Filters: : Grok 来 实现 LogStash: : Inputs: : Syslog 的 。 所 以 你 其 实 可 以 直接 


input { 

tcp { 
port => “8514” 
} 


} 
f?ilter { 
grok { 


match => [ “message” , “%{SYSLOGLINE}” ] 


} 
syslog_pri { } 


如 果 你 已 经 在 使 用 UDP 监听 器 收集 日 志 ， 


建议 在 使 用 LogStash: : Inputs: : Syslog 的 时 候 走 TCP 协 议 来 传输 数据 。 


因为 具体 实现 中 ，UDP 监 听 器 只 用 了 一 个 线程 ， 而 TCP 监 听 器 会 在 接收 每 个 连接 的 时 候 都 启动 新 的 线程 来 处 理 后 续 步 又 。 


下 行 命令 检查 你 的 UDP 接收 队列 大 小 : 


# netstat -plnu | awk 'NR--1 || $4-/:514$/[(print $2}' 


Recv-Q 
228096 


228096 是 UDP 接收 队列 的 默认 最 大 大 小 ， 这 时 候 linux 内 核 开始 丢弃 数据 包 了 ! 


强烈 建议 使 用 LogStash: : Inputs: : TCP 和 LogStash: : Filters: : Grok 配 合 实现 同样 的 syslog 功 能 ! 


虽然 LogStash: : Inputs: : Syslog 在 使 用 TCPServer 的 时 候 可 
能 几何 级 的 下 降 一 一 经 过 测试 ，TCPServer 每 秒 可 以 接收 50000 条 数据 ， 而 在 同一 线程 中 启用 grok 后 每 秒 只 能 处 理 5000 条 ， 再 加 上 date 只 能 达到 500 条 ! 


以 采用 多 线程 处 理 数据 的 接收 ， 但 是 在 同一 个 客户 端 数据 的 处 理 


中 ， 其 grok 和 date 是 一 直 在 该 线程 中 完成 的 ， 这 会 导致 总 体 上 的 处 理性 


才 将 这 两 步 拆 分 到 filters 阶 段 后 ，Logstash 支 持 对 该 阶段 插件 单独 设置 多 线程 运行 ， 大 大 提高 了 总 体 处 理性 能 。 在 相同 环境 下 ，logstash-f tcp.conf-w 20 的 测试 中 ， 总 体 处 理性 能 可 以 达到 每 秒 30000 


条 数据 ! 
Oze 


测试 采用 Logstash 作 者 提供 的 命令 : 


yes “<44>May 19 18:30:17 snack jls: foo bar 32" 


| nc localhost 3000 


出 处 见 : https://github.com/jordansissel/experiments/blob/master/ruby /jruby-netty /syslog-server/Makefile 


如 果 你 实在 没 法 切换 到 TCP 协 议 ， 可 以 自己 写 程序 ， 或 者 使 用 其 


例 : https;//gist.github.com/chenryn/7c922ac424324ee04695, 


2.1.5 ”collectd 输 入 


他 基于 异步 |/O 框 架 (比如 libev) 的 项 目 。 下 面 是 一 个 简单 的 异步 /0 实现 UDP 监 听 数 所 


居 输 入 Elasticsearch 的 示 


collectd 是 一 个 守护 (daemon) 进程 ， 用 来 收集 系统 性 能 和 提供 各 种 存储 方式 来 存储 不 同 值 的 机 制 。 它 会 在 系统 运行 和 存储 信息 时 周期 性 的 统计 系统 的 相关 统计 信息 。 利 用 这 些 信息 有 助 于 查找 当前 系 
统 性 能 瓶颈 (如 作为 性 能 分 析 performance analysis) 和 预测 系统 未 来 的 load (如 能 力 部 署 capacity planning) 等 


下 面 简单 介绍 一 下 : collectd 的 部 署 以 及 与 Logstash 对 接 的 相关 配置 实例 。 


1.collectd 的 安装 


解决 依赖 如 下 : 


rpm -ivh "http://dl.fedoraproject.org/pub/epel/6/1i386/epel-release-6-8.noarch.rpm" 
yum -y install libcurl libcurl-devel rrdtool rrdtool-devel perl-rrdtool 
rrdtool-prel libgcrypt-devel gcc make gcc-c++ liboping liboping-devel perl- 


CPAN net-snmp net-snmp-devel 


源码 安装 collectd 如 下 : 


wget http://collectd.org/f?iles/collectd-5.4.1.tar.gz 


tar zxvf collectd-5.4.1.tar.gz 
cd collectd-5.4.1 


./conf?igure --pref?ix-/usr --sysconfdir-/etc --localstatedir-/var --libdir-/usr/lib 
--mandir-/usr/share/man --enable-all-plugins 


make && make install 


安装 启动 脚本 如 下 : 


cp contrib/redhat/init.d-collectd /etc/init.d/collectd 


chmod +x /etc/init.d/collectd 


启动 collectd 如 下 : 


service collectd start 


2.collectd 的 配置 


以 下 配置 可 以 实现 对 服务 器 基本 的 CPU、 内 存 、 网 卡 流量 、 磁 盘 |/O 以 及 磁盘 空间 占用 情况 的 监 


Hostname “host.example.com” 

LoadPlugin interface 

LoadPlugin cpu 

LoadPlugin memory 

LoadPlugin network 

LoadPlugin df 

LoadPlugin disk 

«Plugin interface» 
Interface “eth0” 
IgnoreSelected false 

«/Plugin» 

«Plugin network» 


«Server ^"10.0.0.1" "25826" > ## Logstash 的 IP 地 址 和 collectd 的 数据 接收 端口 号 


«/Server» 
«/Plugin» 


3.Logstash 的 配置 


以 下 配置 实现 通过 Logstash 监 听 25826 端 口 


简单 配置 示例 如 下 : 


， 接 收 从 collectd 发 送 过 来 的 各 项 检测 数据 。 


input { 


collectd ( 


port => 25826 4b 端口 号 与 发 送 端 对 应 
type => collectd 


推荐 配置 示例 如 下 : 


udp 


{ 


port => 25826 
buffer_size => 1452 


workers => 3 
queue size => 30000 


# Default is 2 
# Default is 2000 


codec => collectd { } 
type => "collectd" 


下 面 是 简单 的 一 个 输出 结果 : 
{ “_index” : “logstash-2014.12.11” , * type" "collectd" , " id" : "dS6vVz4aRtK5xS86kwjZnw' , " score" : null, " source" : ( “host” : "host.example.com" , "Gtimestamp' : “2014- 
] 
) “sort” : [ 
1418279332118 
i 
参考 资料 
“ collectd 支 持 收集 的 数据 类 型 : http://git.verplant.org/p=collectd.git; a=blob; hb=master; £-README 
“ collectd 收 集 各 数据 类 型 的 配置 参考 资料 : http://collectd.org/documentation/manpages/collectd.conf.5.shtml 
- collectd 简 单 配置 文件 示例 : https://gist.github.com/untergeek/ab85cb86a9bf39f1fc6d 
2.2 ” 编 解码 配置 
Codec 是 Logstash 从 1.3.0 版 开始 新 引入 的 概念 (Codec 来 自 Coder/decoder 两 个 单词 的 首 字母 缩写 ) 。 
在 此 之 前 ，Logstash 只 支持 纯 文 本 形式 输入 ， 然 后 以 过 滤器 处 理 它 。 但 现在 ， 我 们 可 以 在 输入 期 处 理 不 同类 型 的 数据 ， 这 全 是 因为 有 了 Codec 设 置 。 


所 以 , 这 


Codec 的 引入 ， 使 得 Logstash 可 以 更 好 、 更 方便 地 与 


事实 上 ， 我 们 在 第 一 个 “Hello World" 上 
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这 个 五 段 式 的 流程 说 明 源 自 Pen 版 的 Logstash (后 来 改名 叫 Message: 


2.2.1 


在 早期 的 版 本 中 ， 有 一 种 降低 Logstash 过 滤器 的 CPU 负载 消耗 的 做 法 盛行 了 


这 个 建议 依然 有 效 ， 不 过 在 当前 版 本 中 需要 稍微 做 一 点 配置 变动 ， 


需要 纠正 之 前 的 一 个 概念 。 


例 中 就 已 经 上 


JSON 编 解码 


1. 配 置 示例 


社 


区 常 


logformat json 


见 的 示例 都 是 


'{ “@timestamp” 


"Qversion' : “1 
"host" : “ 


erver addr” , 

" 1 *Sremote addr” ,' 
" :$body bytes sent, ' 
"responsetime" :$request time, i 


"domain" : “$host” ,' 
tc url! i "Puri? ,' 
"status" : "$status" }'; 


access log /var/log/nginx/access.log json json; 


: “$time iso8601" ,' 
» eT 
' 


过 Codec 了 一 一 rubydebug 就 是 一 种 Codec! 虽然 它 一 般 只 会 


的 Apache 的 customlog， 不 过 我 觉得 Nginx 是 一 个 比 Apache 更 常 


Logstash 不 只 是 一 个 inputlfilterloutput 的 数据 流 ， 而 是 一 个 inputldecodelfilterlencodeloutput 的 数据 流 ! 


Codec 就 是 


来 decode、encode 事 件 的 。 


其 他 有 自 定义 数据 格式 的 运 维 产品 共存 ， 比 如 graphite、fluent、netflow、collectd， 以 及 使 用 msgpack、json、edn 等 通用 数据 格式 的 其 他 产品 


因为 现在 有 专门 的 Codec 设 置 。 


在 stdout 插 件 中 ， 作 为 配 


: Passing 模 块 ) 的 设计 。 本 书 稍 后 5.8 节 会 对 该 模块 稍 作 介绍 。 


的 新 型 Web 服 务 器 ， 所 以 我 这 里 会 


测试 或 者 调试 的 工具 。 


社区 (在 当时 的 Cookbook 上 有 专门 的 一 节 介绍 ) : 直接 输入 预定 义 好 的 JSON 数 据 ， 这 样 就 可 以 省 略 掉 filter/grok 配 置 ! 


nginx.conf 做 示例 : 


注意 ， 在 $request_time 和 $body_bytes_sent 变 量 两 头 没有 双 引 号 "， 这 两 个 数据 在 JSON 里 应 该 是 数值 类 型 ! 
重启 Nginx 应 用 ， 然 后 修改 你 的 input/file 区 段 配置 成 下 面 这 样 : 
input 1{ 

f?ile ( 


l 


path => "/var/log/nginx/access.log json" “ 


codec => json 


下 面 访问 一 下 你 Nginx 发 布 的 Web 页 面 ， 然 后 你 会 看 到 Logstash 进 程 输出 类 似 下 面 这 样 的 内 容 : 


{ "Gtimestamp' => “2014-03-21T18:52:25.000+08:00” , “@version” => “1” , “host” => "raochenlindeMacBook-Air.local' , 
l 


“client” => “123.125.74.53” , “size” =>8096, "responsetir 


3.Nginx 代 理 服务 的 日 志 格式 问题 


对 于 一 个 Web 服 务 器 的 访问 日 志 ， 看 起 来 已 经 可 以 很 好 的 工作 了 。 不 过 如 果 Nginx 是 作为 一 个 代理 服务 器 运行 的 话 ， 访 问 日 志 里 有 些 变量 ， 比 如 说 $upstream_response time， 可 能 不 会 一 直 是 数字 ， 


它 也 可 能 是 一 个 “-” 字 符 串 ! 这 会 直接 导致 Logstash 对 输入 数据 验证 报 异 常 。 


有 两 个 办 法 解决 这 个 问题 : 


1) 用 sed 在 输入 之 前 先 蔡 换 -成 0。 运 行 Logstash 进 程 时 不 再 读 取 文 件 而 是 标准 输入 ， 这 样 命令 就 成 了 下 面 这 个 样子 : 


tail -F /var/log/nginx/proxy access.log json \ 
| sed 's/upstreamtime ":-/upstreamtime" :0/' \ 
| /usr/local/logstash/bin/logstash -f /usr/local/logstash/etc/proxylog.conf 


2) 日 志 格式 中 统一 记录 为 字符 串 格式 ( 即 都 带 上 双 引 号 ") ， 然 后 再 在 Logstash 中 用 filte mutate 插 件 来 变更 应 该 是 数值 类 型 的 字符 字段 的 值 类 型 。 


有 关 LogStash: : Filters: : Mutate 的 内 容 ， 本 书 稍 后 会 有 介绍 。 


222 ”多 行事 件 编码 


有 些 时 候 ， 应 用 程序 调试 日 志 会 包含 非常 丰富 的 内 容 ， 为 一 个 事件 打印 出 很 多 行内 容 。 这 种 日 志 通 常 都 很 难 通 过 命令 行 解析 的 方式 做 分 析 。 


而 Logstash 正 为 此 准备 好 了 codec/muiltiline 揪 件 ! 当然 ，multiline 播 件 也 可 以 用 于 其 他 类 似 的 堆栈 式 信息 ， 比 如 Linux 的 内 核 日 志 。 


配置 示例 如 下 : 


codec => multiline { 
pattern =>“^\[” 
negate => true 
what => "previous" 


} 


运行 Logstash 进 程 ， 然 后 在 等 待 输入 的 终端 中 输入 如 下 几 行 数据 : 


[Aug/08/08 14:54:03] hello world 
[Aug/08/09 14:54:04] hello logstash 
hello best practice 
hello raochenlin 
[Aug/08/10 14:54:05] the end 


你 会 发 现 Logstash 输 出 下 面 这 样 的 返回 : 


{ "Gtimestamp' =>“2014-08-09T13:32:03.3682”， “message” => "[Aug/08/08 14:54:03] hello world\n” , “@version” => “1” , “host” => "raochenlindeMacBook-Air.local" 


( "Gtimestamp' => "2014-08-09T13:32:24.359Z2" , “message” => "[Aug/08/09 14:54:04] hello logstash\n\n hello best practice\n\n 


hello raochenlinWn" , “@version” => “1” , "tags" => [ 
0] “multiline” 
], “host” => *raochenlindeMacBook-Air.local" 


你 看 ， 后 面 这 个 事件 ， 在 “message” 字 段 里 存储 了 三 行 数 据 ! 


输出 的 事件 中 没有 最 后 一 行 的 "the end" 字 符 串 ， 这 是 因为 你 最 后 输入 的 回 车 符 \n 并 不 匹配 设 定 的 从 [正则 表达 式 ，Logstash 还 得 等 下 一 行 数 据 直 到 匹配 成 功 后 才 会 输出 这 个 事件 。 


见 : https;//github.com/logstash-plugins/logstash-patterns-core/blob/master/patterns/java 


说 到 应 用 程序 日 志 ，Log4j 肯 定 是 第 一 个 被 大 家 想到 的 ， 使 用 codec/multiline 也 确实 是 一 个 办 法 。 


不 过 ， 如 果 你 本 身 就 是 开发 人 员 ， 或 者 可 以 推动 程序 修改 变更 的 话 ，Logstash 还 提供 了 另 一 种 处 理 Log4j 的 方式 : input/log4j。 与 codec/multiline 不 同 ， 这 个 插件 是 直接 调用 了 


org.apache.log4j.spi.LoggingEvent 处 理 TCP 端 口 接收 的 数据 。 稍 后 章节 会 详细 讲述 Log4j 的 用 法 。 


2.2.3 ”网 络 流 编码 


NetFlow 是 Cisco 发 明 的 一 种 数据 交换 方式 。NetFlow 提 供 网 络 流量 的 会 话 级 视图 ， 记 录 下 每 个 TCP/IP 事 务 的 信息 。 它 的 目的 不 是 像 tcpdump 那 样 提供 网 络 流量 的 完整 记录 ， 而 是 汇集 起 来 形成 更 易于 


管理 和 易 读 的 流向 和 容量 的 分 析 监 控 。 


Cisco 上 配置 NetFlow 的 方法 ， 请 参照 具体 的 设备 说 明 ， 主 要 是 设 定 采 集 服务 器 的 地 址 和 端口 ， 为 运行 Logstash 服 务 的 主机 地 址 和 端口 


采集 NetFlow 数 据 的 Logstash 服 务 配置 示例 如 下 : 


其 实 这 个 插件 的 原理 很 简单 ， 就 是 把 当前 行 的 数据 添加 到 前 面 一 行 后 面 ， 直 到 新 进 的 当前 行 匹配 ^\[ 正 则 为 止 。 这 个 正则 还 可 以 用 grok 表 达 式 ， 稍 后 你 就 会 学 习 这 方面 的 内 容 。 具 体 的 Java 日 志 正则 


(示例 中 为 9995) 。 


{ 
port => 9995 
codec => netf?low { 
definitions => “/opt/logstash-1.4.2/lib/logstash/codecs/netflow/netflow.yaml” 
versions => [5] 


} 


l 
l 
output { 
elasticsearch ( 
index => "logstash netf?low5- 
host => "localhost" 
} 
} 


$ (4 YYYY .MM. dd) " 


该 插件 生成 的 字段 较 多 ， 所 以 建议 对 应 的 Elasticsesarch 索 引 模板 也 需要 单独 提交 : 
* curl -XPUT localhost:9200/ template/logstash netf?lowS -d '( "template" "logstash netflow5-*" , "settings" : ( 
"index. refresh interval” : “5s” 
A rcu : 
i default ' EMT 
“all” : ( “enabled” : false], 
"properties" es 
"Qversion' : { “index” : “analyzed” , “type” "integer" }, 
"Qtimestamp' : ( “index” "analyzed' , "type" "date" }, 
"netf?low" : ( 
"dynamic" : true, 
"type" "object" , 
"properties" 3 { 
"version" : { "index" "analyzed" , “type” “integer” }, 
“£2?1ow | seq ] num" : { "index" "not | analyzed" "type" "long" }, 
“engine | type" : { "index" “not _analyzed” » " "type" "integer" }, 
“engine: id : { “index” “not | analyzed" , “type” “integer” ], 
“sampling . algorithm” : { “index” "not analyzed' , "type" "integer" ], 
“sampling: interval” : { “index “not analyzed” , “type “integer” }, 
"f?low records" { "index" : “not analyzed "type" : "integer" ], 
ipv4 ; src addr' : ( "index "analyzed “type” : "ip" ], 
“ipv4 dst addr” : { “index” "analyzed" "type" : “ip ], 
“ipv4 1 | next der { "index" "analyzed" , "type" : “ip” }, 
“input snmp” : { “index” "not analyzed” , "type" : “long” }, 
“output ; snmp” : { “index “not | analyzed" 1 "type" "long" }, 
“in pkts" : { l'index" : "analyzed" È “type” "long" }, 
“in bytes” : { “index” “analyzed” , “type” long” }, 
"f?irst switched" : { “index” “not _analyzed” , “type” : "date" }, 
"last Switched" : { "index" “not | analyzed" "type" "date" ], 
"14 | src port : { "index" “analyzed” n "type? "long" }, 
"14 [ dst port" : { index" “analyzed” " "b pe" "long" }, 
"tcp flags" : ( "index" “analyzed” , "type" "integer" }, 
“protocol” : { “index” “analyzed” , “type” “integer” }, 
"src tos" : ( “index” “analyzed” , "type" : “integer” ], 
"src as”: ( "index" "analyzed" , "type" "integer" }, 
dst as' : { “index” : “analyzed”, “type” "integer" }, 
"src mask' : ( "index" "analyzed' , "type" "integer" }, 
"dst mask” : ( “index” "analyzed" , "type" "integer" } 


Elasticsearch 索 引 模 板 的 功能 ， 本 书 稍 后 12.6 节 会 有 详细 介绍 。 


过 滤器 的 原始 数据 ， 进 行 复杂 的 逻辑 处 


2.3 ”过 滤器 配置 

有 丰富 的 过 滤器 插件 ， 是 Logstash 威 力 如 此 强大 的 重要 因素 。 名 为 过 滤器 ， 其 实 提供 的 不 单单 是 过 滤 的 功能 。 下 面 我 们 就 会 重点 介绍 几 个 插件 ， 它 们 扩展 了 进入 过 
理 ， 甚 至 可 以 无 中 生 有 地 添加 新 的 Logstash 事 件 到 后 续 的 流程 中 去 ! 
2.3.1 date 时 间 处 理 

之 前 章节 已 经 提 过 ，logstash-filter-date 插 件 可 以 用 来 转换 你 的 日 志 记录 中 的 时 间 字 符 串 ， 变 成 LogStash: : Timestamp 对 象 ， 然 后 转 存 到 @timestamp 字 段 里 。 


这 在 导入 旧 数 据 的 时 候 固然 非常 有 
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， 而 在 实时 数据 处 理 的 时 候 同样 有 效 ， 


因为 一 般 情 况 下 数据 流程 中 我 们 都 会 有 缓冲 


区 ,导致 最 终 的 实际 处 理 时 间 跟 导 


强烈 建议 打开 Nginx 的 access_log 配 置 项 的 buffer 参 数 ， 对 极限 响应 性 能 有 极 大 提升 ! 


1 配置 示例 
logstash-filter-date 插 件 支 持 五 种 时 间 格 式 : 


: ISO8601: 


$time_iso8601 变 量 来 记录 请 求 时 间 成 这 种 格式 。 


“ UNIX: UNIX 时 间 惟 格式 ， 记 录 的 是 从 1970 年 起 始 至 今 的 总 秒 数 。 


类 似 “2011-04-19T03: 44: 01.103Z” 这 样 的 格式 。 具 体 Z 后 面 可 以 有 “08: 00” 也 可 以 没有 ， 
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.103” 这 个 也 可 以 没有 。 常 用 场景 里 来 说 ， 


式 中 就 使 用 了 这 种 格式 。 


“ UNIX MS: 这 个 时 间 玲 则 是 从 1970 年 起 始 至 今 的 总 毫秒 数 。 据 我 所 知 ，JavaSctipt 里 经 常 使 用 这 个 时 间 格 式 。 


“TAI64N: TAI64N 格 式 比较 少见 


， 是 这 个 样子 的 : (@4000000052f88ea32489532c。 我 目前 只 知道 常见 应 用 中 ，qmail 会 用 这 个 格式 。 


件 产生 时 间 略 有 偏差 。 


Nginx 的 log_format 配 置 里 就 可 以 使 用 


“Joda-Time 库 : Logstash 内 部 使 用 了 Java 的 Joda 时 间 库 来 作 时 间 处 理 。 所 以 我 们 可 以 使 用 Joda 库 所 支持 的 时 间 格式 来 作 具 体 定义 。Joda 时 间 格 式 定义 见 表 2-1。 


表 2-1 Joda 时 间 库 格 式 


CET) CNN: 
a [| « < — [| e |% 
yo 

T 
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下 面 我 们 写 一 个 Joda 时 间 格 式 的 配置 作为 示例 : 


N 


filter { 
grok { 
match => [ “message” , “%{HTTPDATE:logdate}” ] 
l 
date ( 
match => [ “logdate” , "dd/MMM/yyyy:HH:mm:ss Z” ] 
} 
} 


注意 ， 时 区 偏 移 量 只 需要 用 一 个 字母 Z 即 可 。 


2. 时 区 问题 的 解释 


很 多 中 国 用 户 经 常 提 一 个 问题 : 为 什么 @timestamp 比 我 们 早 了 8 个 小 时 ?人 怎么 修改 成 北京 时 间 ? 


其 实 ，Elasticsearch 内 部 ， 对 时 间 类 型 字段 ， 是 统一 采用 UTC 时 间 ， 存 成 ong 长 整形 数据 的 ! 对 日 志 统 一 采用 UTC 时 间 存储 ， 是 国际 安全 / 运 维 界 的 一 个 通 识 一 一 欧美 公司 的 服务 器 普遍 广泛 分 布 在 多 
个 时 区 里 一 一 不 像 中 国 ， 地 域 横 跨 五 个 时 区 却 只 用 北京 时 间 。 


对 于 页 面 查看 ，ELK 的 解决 方案 是 在 Kibana 上 ， 读 取 浏 览 器 的 当前 时 区 ， 然 后 在 页 面 上 转换 时 间 内 容 的 显示 。 


所 以 ， 建 议 大 家 接受 这 种 设 定 。 否 则 ， 即 便 你 用 .getLocalTime 修 改 ， 也 还 要 面临 在 Kibana 过 去 修改 ， 以 及 Elasticsearch 原 有 的 ["now-1h"TO"now"] 这 种 方便 的 搜索 语句 无 法 正常 使 用 的 姑 众 。 


以 上 ， 请 读者 自行 项 酌 。 


2.32 grok 正 则 捕获 


grok 是 Logstash 最 重要 的 插件 。 你 可 以 在 grok 里 预定 义 好 命名 正则 表达 式 ， 在 稍 后 (grok 参 数 或 者 其 他 正则 表达 式 里 ) 引用 它 。 
1. 正 则 表达 式 语法 


运 维 工程 师 多 多 少 少 都 会 一 点 正则 。 你 可 以 在 grok 里 写 标准 的 正则 ， 像 下 面 这 样 : 


\s+ (? «request time>\d+ (? : NV. Nd) ? ) \s+ 


这 个 正则 表达 式 写 法 对 于 Per| 或 者 Ruby 程 序 员 应 该 很 熟悉 了 ，Python 程 序 员 可 能 更 习惯 写 (? P«name» pattern) ， 没 办 法 ， 适 应 一 下 吧 。 


现在 给 我 们 的 配置 文件 添加 第 一 个 过 滤器 区 段 配置 。 配 置 要 添加 在 输入 和 输出 区 段 之 间 (Logstash 执 行 区 段 的 时 候 并 不 依赖 于 次 序 ， 不 过 为 了 自己 看 得 方便 ， 还 是 按 次 序 书写 吧 ) : 


input {stdin{}} 
filter ( 
grok { 
match => { 
“message” => “\s+ (? <request_time>\d+ (? : \.\d+) ? ) Ns" 


} 


l 
output {stdout{}} 


运行 Logstash 进 程 然后 输入 “begin 123.456 end" ， 你 会 看 到 类 似 下 面 这 样 的 输出 : 


{ “message” => “begin 123.456 end” , “@version” => “1” , "Gtimestamp' =>“2014-08-09T11:55:38.1862”,，“host” => "raochenlindeMacBook-Air.local" , "request time" => “123.456” 
} 


漂亮 ! 不 过 数据 类 型 好 像 不 太 满意 .…….request_time 应 该 是 数值 而 不 是 字符 串 。 


我 们 已 经 提 过 稍 后 会 学 习 用 LogStash: : Filters: : Mutate 来 转换 字段 值 类 型 ， 不 过 在 grok 里 ， 其 实 有 自己 的 魔法 来 实现 这 个 功能 ! 


2.grok 表 达 式 语法 


grok 支 持 把 预定 义 的 grok 表 达 式 写 入 到 文件 中 ， 官 方 提供 的 预定 义 grok 表 达 式 见 : https://github.com/logstash-plugins/logstash-patterns-core/tree/master/patterns。 


下 面 是 从 官方 文件 中 摘抄 的 最 简单 但 是 足够 说 明 用 法 的 示例 : 


USERNAME [a-zA-20-9. -]+ 
USER $(USERNAME]) 


第 一 行 ， 用 普通 的 正则 表达 式 来 定义 一 个 grok 表 达 式 ; 第 二 行 ， 通 过 打印 赋值 格式 ， 用 前 面 定义 好 的 grok 表 达 式 来 定义 另 一 个 grok 表 达 式 。 


grok 表 达 式 的 打印 复制 格式 的 完整 语法 见 下 行 示例 。 其 中 data_type 目 前 只 支持 两 个 值 : int 和 float。 


$(PATTERN NAME:capture name:data type] 


所 以 我 们 可 以 改进 我 们 的 配置 成 下 面 这 样 : 


filter ( 
grok ( 
match => { 
“message” => "S(WORD) %{NUMBER:request_time:float} %{WORD}” 


Imi 
Ti 


新 运行 进程 然后 可 以 得 到 如 下 结果 : 


{ “message” => "begin 123.456 end” , “@version” => “1” , "Gtimestamp' => “2014-08-09T12:23:36.6342” , “host” => "raochenlindeMacBook-Air.local" , "request time" => 123.456 
l 


这 次 request time 变 成 数值 类 型 了 。 


3. 最 佳 实践 


实际 运用 中 ， 我 们 需要 处 理 各 种 各 样 的 日 志文 件 ， 如 果 你 都 是 在 配置 文件 里 各 自 写 一 行 自己 的 表达 式 ， 就 完全 不 可 管理 了 。 所 以 ， 我 们 建议 是 把 所 有 的 grok 表 达 式 统一 写 入 到 一 个 地 方 。 然 后 


filter/grok 的 patterns_dir 选 项 来 指明 。 


message 字 段 ， 只 保留 最 重要 的 部 分 。 


重 写 参数 的 示例 如 下 : 


如 果 你 把 “message” 里 所 有 的 信息 都 grok 到 不 同 的 字段 了 ， 数 据 实 质 上 就 相当 于 是 重复 存储 了 两 份 。 所 以 你 可 以 用 remove _field 参 数 来 删除 掉 message 字 段 ， 或 者 用 overwrite 参 数 来 重 写 默 认 的 


filter ( 
grok ( 
patterns dir => "/path/to/your/own/patterns" 
match => ( 
"message" => "S(SYSLOGBASE) $(DATA:message]" 


overwrite => [ “message” ] 


} 


4. 高 级 用 法 


| 多 行 匹配 在 和 codec/multiline 搭 配 使 用 的 时 候 ， 需 要 注意 一 个 问题 ，grok 正 则 和 普通 正则 一 样 ， 默 认 是 不 支持 匹配 回 车 换行 的 。 就 像 你 需要 =~//m 一 样 也 需要 单独 指定 ， 具 体 写法 是 在 表达 式 开 始 位 


Em (? m) 标记 。 如 下 所 示 : 


match => ( "message" => " (? m) \s+ (? «request time>\d+ (? : \.\d+) ? ) Ns" 
} 


“ 多 项 选择 ”有 时 候 我 们 会 碰 上 一 个 日 志 有 多 种 可 能 格式 的 情况 。 这 时 候 要 写成 单一 正则 就 比较 困难 ， 或 者 全 用 | 隔 开 又 比较 丑陋 。 


这 时 候 ，Logstash 的 语法 提供 给 我 们 一 个 有 趣 的 解决 方式 。 


文档 中 ， 都 说 明 logstash-filters-grok 插 件 的 match 参 数 应 该 接受 的 是 一 个 Hash 值 。 但 是 因为 早期 的 Logstash 语 法 中 Hash 值 也 是 
没 问题 。 所 以 ， 我 们 这 里 其 实 可 以 传递 多 个 正则 来 匹配 同一 个 字段 : 


[这 种 方式 书写 的 ， 所 以 其 实现 在 传递 Array 值 给 match 参 数 也 完全 


match => [ "message" , ^" (? «request time>\d+ (? : \.\d+) ? ) " , "message" , "$(SYSLOGBASE) $(DATA:message])" , "message" , “ (? m) $(WORD)" 
] 


Logstash 会 按照 这 个 定义 次 序 依次 尝试 匹配 ， 到 匹配 成 功 为 止 。 虽 说 效果 跟 用 | 分 割 写 个 大 大 的 正则 是 一 样 的 ， 但 是 可 阅读 性 好 了 很 多 。 


Oez 


我 强烈 建议 每 个 人 都 要 使 用 Grok Debugger. (http://grokdebug.herokuapp.com/) 来 调试 自己 的 grok 表 达 式 。 


2.3.3 ”GeolP 地 址 查询 


GeolP 是 最 常见 的 免费 |P 地 址 归 类 查询 库 ， 同 时 也 有 收费 版 可 以 采购 。GeolP 库 可 以 根据 IP 地 址 提供 对 应 的 地 域 信息 ， 包 括 国 别 、 省 市 、 经 纬度 等 ， 对 于 可 视 化 地 图 和 区 域 统计 非常 有 用 。 


配置 示例 如 下 : 


filter { 


geoip { P 
source => message 
} 


运行 结果 如 下 : 


{ “message” => “183.60.92.253” , “@version” => “1” , "Gtimestamp' => “2014-08-07T10:32:55.6102” , “host” => “raochenlindeMacBook-Air.local” , “geoip? => { “ip” => “183.60.92.2 
[0] 113.25 
[1] 23.11670000000001 
] 


GeolP 库 数据 较 多 ， 如 果 你 不 需要 这 么 多 内 容 ， 可 以 通过 fields 选 项 指定 自己 所 需要 的 。 下 例 为 全 部 可 选 内 容 : 


filter { 
geoip { 
f?ields => [ "city name' , "continent code” , “country code2" , 
"country code3" , country name" , “dma code" , “ip”, "latitude" , 
"longitude" , "postal code" , "region name" , “timezone” 


需要 注意 的 是 : geoip.location 是 Logstash 通 过 latitude 和 longitude 额 外 生成 的 数据 。 所 以 ， 如 果 你 是 想 要 经 纬度 又 不 想 重复 数据 的 话 ， 应 该 像 下 面 这 样 做 : 


filter ( 
geoip ( 
fields => [ "city name" , "country code2" , "country name" , "latitude" , 
"longitude" , “region name" 
remove field => [ "[geoipl[latitude]" , "[geoip][longitude]" ] 
li 


还 要 注意 : geoip 插 件 的 “source” 字 段 可 以 是 任 一 处 理 后 的 字段 ， 比 如 “client_ip” ， 但 是 字段 内 容 却 需要 小 心 ! Geolp 库 内 只 存 有 公共 网 络 上 的 IP 信 息 ， 查 询 不 到 结果 的 ， 会 直接 返回 null， 而 
Logstash 的 Geolp 插 件 对 null 结 果 的 处 理 是 : “不 生成 对 应 的 geoip. 字 段 ”。 所 以 读者 在 测试 时 ， 如 果 使 用 了 诸如 127.0.0.1、172.16.0.1、182.168.0.1、10.0.0.1 等 内 网 地 址 ， 会 发 现 没有 对 应 输出 ! 


2.3.4 JSON 编 解码 


在 上 一 章 ， 已 经 讲 过 在 Codec 中 使 用 JSON 编 码 。 但 是 ， 有 些 日 志 可 能 是 一 种 复合 的 数据 结构 ， 其 中 只 有 一 部 分 记录 是 JSON 格 式 的。 这 时 候 ， 我 们 依然 需要 在 filter 阶 段 ， 单 独 启用 JSON 解 码 插件 。 


配置 示例 如 下 : 


filter { 
json { 
source => “message” 
target => “jsoncontent” 
} 


运行 结果 如 下 : 


( “@version” : “1” , “@timestamp” : “2014-11-18T08:11:33.0002” , "host" : “webl21.mweibo.tc.sinanode.com” , "message" : “{\” uid\ “:3081609001,\” type\ ":V' signal\ “}” , “jsoncc 
} 
i 


如 果 不 打算 使 用 多 层 结 构 的 话 ， 删 掉 target 配 置 即 可 。 单 层 结构 新 的 结果 如 下 : 


[ “@version” : “1” , “@timestamp” : “2014-11-18T08:11:33.0002” , "host" : "webl21.mweibo.tc.sinanode.com" , "message" : “{\” uid\ “:3081609001,\” type\ “:\” signalN “}” , "uid" : 
} 


2.3.5 ”key-value 切 分 


在 很 多 情况 下 ， 日 志 内 容 本 身 都 是 一 个 类 似 于 key-value 的 格式 ， 但 是 格式 具体 的 样式 却 是 多 种 多 样 的 。Logstash 提 供 Ilogstash-filter-kv 插 件 ， 帮 助 处 理 不 同样 式 的 key-value 日 志 ， 变 成 实际 的 
LogStash: : Event 数 据 。 


配置 示例 如 下 : 


filter { 
ruby { 
init => “@kname = ['method','uri','verb']" 
code => “event.append (Hash [@kname.zip (event['request'].split ( ' ) )])” 


if [uri] { 
ruby { 
init => “@kname = ['url path','url args']" 
code => “event.append (Hash[Gkname.zip (event['uri'].split ( '2 ) ) 1) " 
} 
kv ( 
pref?ix => "url " 
source => "url args" 
field split =>“& 
remove field => [ "url args' , “uri”, "request" ] 


Nginx 访 问 日 志 中 的 $request， 通 过 这 段 配置 ， 可 以 详细 切 分 成 method、url_path、verb、url_a、url_bhttp://www.hzcourse.comyVresource/readBook? 
path-/openresources/teach ebook/uncompressed/15426/OEBPS/Text/... 


进一步 ， 如 果 url_args 中 有 过 多 字段 ， 可 能 导致 Elasticsearch 集 群 因为 频繁 update mapping 或 者 消耗 太 多 内 存在 cluster state 上 而 宕 机 。 所 以 ， 更 优 的 选择 是 只 保留 明确 有 用 的 url_args 内 容 ， 其 他 部 
分 舍 去 ， 如 下 所 示 : 


kv { 
prefix => "url " 
source — "url args" 
field split => "& 
include keys => [ “uid”, “cip” ] 
remove field => [ "url args' , “uri”, “request” ] 


上 例 即 表示 ， 除 了 url_uid 和 url_cip 两 个 字段 以 外 ， 其 他 的 url_* 都 不 保留 。 


2.3.6 ”metrics 数 值 统计 


logstash-filter-metrics 插 件 是 使 用 Ruby 的 Metriks 模 块 来 实现 在 内 存 里 实时 地 计数 和 采样 分 析 。 该 模块 支持 两 个 类 型 的 数值 分 析 : meter 和 timer。 下 面 分 别 举例 说 明 。 


1.Meter 示 例 (速率 阔 值 检测 ) 


Web 访 问 日 志 的 异常 状态 码 频率 是 运 维 人 员 会 非常 关心 的 一 个 数据 。 通 常 我 们 的 做 法 是 通过 Logstash 或 者 其 他 日 志 分 析 脚 本 ， 把 计数 发 送 到 rrdtoo| 或 者 graphite 里 面 ， 然 后 再 通过 check_graphite 脚 
本 之 类 的 东西 来 检查 异常 并 报警 。 


事实 上 这 个 事情 可 以 直接 在 Logstash 内 部 就 完成 。 比 如 如 果 最 近 一 分 钟 504 请 求 的 个 数 超过 100 个 就 报警 ， 如 下 所 示 : 


filter ( 
metrics { 
meter => "error.$(status)" 
add tag => "metric" 
ignore older than => 10 


if “metric” in [tags] { 
ruby ( 
code => "event.cancel if event['error.504.rate 1m'] * 60 « 100" 
} 
} 
} 
output { 
if “metric” in [tags] { 
exec { 
command => "echo V' Out of threshold: %{error.504.rate_1m}\ "" 


l 


这 里 需要 注意 *60 的 含义 。metrics 模 块 生成 的 rate_1m/5m/15m 意 思 是 : 最 近 1、5、15 分 钟 的 每 秒 速 率 ! 


2.Timer 示 例 (box and whisker 异 常 检 测 ) 


官 版 的 logstash-filter-metrics 揪 件 只 适用 于 metric 事 件 的 检查 。 由 揪 件 生成 的 新 事件 内 部 不 存 有 来 自 input 区 段 的 实际 数据 信息 。 所 以 ， 要 完成 我 们 的 百分比 分 布 箱 体检 测 ， 需 要 首先 对 代码 稍微 做 几 
行 变动 ， 即 在 metric 的 timer 事 件 里 加 一 个 属性 ， 存 储 最 近 一 个 实际 事件 的 数值 : https://github.com/chenryn/logstash/commit/bc7bf34caf551d8a149605cf28e7c5d33fae7458 


然后 我 们 就 可 以 用 如 下 配置 来 探测 异常 数据 了 : 


filter { 
metrics { 
timer => { “rt” => “%{request time)" } 
percentiles => [25, 75] B 
add tag => "percentile" 


if "percentile" in [tags] ( 
ruby { 
code => "l1-event ['rt.p75']-event['rt.p25'];event['rt.low'] 
-event['rt.p25']-l;event|'rt.high']-event['rt.p75']4l" 
} 
} 


} 
output { 
if “percentile” in [tags] and ([rt.last] > [rt.high] or [rt.last] < [rt.low]) { 
exec { 
command => "echo V' Anomaly: $(rt.last)N “” 


} 


Qez 
A Xbox and shisker poth 容 和 重要 性 ， 参 见 《 数 据 之 魅 》 一 书 。 
2.3.7 mutate 数据 修改 


logstash-filter-mutate 插 件 是 Logstash 另 一 个 重要 插件 ， 它 提供 了 丰富 的 基础 类 型 数据 处 理 能 力 ， 包 括 类 型 转换 、 字 符 串 处 理 和 字段 处 理 等 。 


1. 类 型 转换 


类 型 转换 是 logstash-filter-mutate 插 件 最 初 诞生 时 的 唯一 功能 。 其 应 用 场景 在 之 前 JSON 编 解码 小 节 已 经 提 到 。 
可 以 设置 的 转换 类 型 包括 : "integer", “float” 和 “string”。 示 例如 下 : 


filter ( 
mutate ( 
convert => [ "request time" , "float" ] 


Qua 


mutate 除 了 转换 简单 的 字符 值 ， 还 支持 对 数组 类 型 的 字段 进行 转换 ， 即 将 [“1”，“2”] 转 换 成 [ ，2]。 但 不 支持 对 哈 希 类 型 的 字段 做 类 似 处 理 。 有 这 方面 需求 的 可 以 采用 稍 后 讲述 的 logstash-filter-ruby 插 


2. 字 符 串 处 理 
有 如 下 字符 串 处 理 的 插件 : 


“ gsub: 仅 对 字符 囊 类 型 字段 有 效 。 


gsub => [ “urlparams” , “IWA”, “”] 


“ split: 分 割 字 符 串 。 


filter { 
mtate { 
split => [ “message” , “|”] 
i 


随意 输入 一 捉 以 | 分 割 的 字符 ， 比 如 “123|321|adfdjdfjld*=123”， 可 以 看 到 如 下 输出 : 


{ "message" => [ 
[0] "123", 
ul] “321° , 
[2] "adfd' , 


[3] *afjld*-123" 
], "(version' => “1” , "Gtimestamp' => "2014-08-20T15:58:23.120Z" , “host” => "raochenlindeMacBook-Air.local" 


* join: 仅 对 数组 类 型 字段 有 效 。 


我 们 在 之 前 已 经 用 split 割 切 的 基础 上 再 join 回去 。 配 置 改 成 : 


filter ( 
mutate ( 
split => [ “message” , “|” ] 


mutate ( 
join => [ “message” , 


i 


filter 区 段 之 内 ， 是 顺序 执行 的 。 所 以 我 们 最 后 看 到 的 输出 结果 是 : 


{ “message” => “123,321,adfd,dfjld*=123” , “@version” => “1” , “@timestamp” => “2014-08-20T16:01:33.9722” , “host” => "raochenlindeMacBook-Air.local" 
i 


| merge: 合并 两 个 数组 或 者 哈 希 字段 。 依 然 在 之 前 split 的 基础 上 继续 : 


filter { 
mutate { 
split => [ “message” , “|”] 
i 
mutate { 
merge => [ "message' , "message" ] 


} 


我 们 会 看 到 输出 : 


{ "message" => [ 

“123”， 

3 a 
“adfd”， 
"dfjld*-123" , 


"dfjld*-123" 
], "(version' => “1” , "Gtimestamp' => "2014-08-20T16:05:53.711Z" , “host” => "raochenlindeMacBook-Air.local" 


如 果 src 字 段 是 字符 串 ， 会 自动 先 转换 成 一 个 单元 素 的 数组 再 合并 。 把 上 一 示例 中 的 来 源 字段 改 成 “host” : 


filter ( 
mutate ( 
split => [ “message” , “|” ] 


mutate ( 
merge => [ “message” , “host” ] 


"dfjld*-123" , 
"raochenlindeMacBook-Air.local" 


], "Gversion" => “1” , “timestamp” => "2014-08-20716:07:53.5332" , "host" => [ 
[0] "raochenlindeMacBook-Air.local" 
] 


us UM IHÍO 


看 ， 目 的 字段 “message” 确 实 多 了 一 个 元 素 ， 但 是 来 源 字 段 “host” 本 身 也 由 字符 串 类 型 变 成 数组 类 型 了 ! 


同样 ， 如 果 目 的 字段 不 是 数组 ， 也 会 被 强制 转换 。 即 使 来 源 字 段 并 不 存在 : 


filter ( 
mutate ( 
merge => [ "message" , “not exist field" ] 
} 


结果 会 变 成 
{ "message" => [ 
[0] ^*123|321ladfdl|d£j1d*-123" 
], “@version” => “1” , “@timestamp” => “2014-08-20T15:58:23.1202” , “host” => "raochenlindeMacBook-Air.local" 


stp: 去 除 字段 内 容 前 后 的 空格 。 可 以 接受 数组 参数 : 


filter ( 
mutate ( 
strip => [ "syslog message" , “syslog datetime" ] 
} 


lowercase: 将 字段 内 容 全 部 转换 成 小 写字 母 。 同 样 可 以 接受 数组 。 在 ELK stack 场 景 中 ， 将 内 容 转换 成 小 写 会 是 一 个 比较 常见 的 需求 。 因 为 Elasticsearch 默 认 是 统一 按照 小 写字 母 来 搜索 的 。 为 了 确保 检 
索 准确 率 ， 在 不 影响 使 用 的 情况 下 ， 建 议 对 常用 检索 字段 启用 lowercase 配 置 。 


- uppercase: 将 字段 内 容 全 部 转换 成 大 写字 母 。 同 样 可 以 接受 数组 。 
3. 字 段 处 理 
字段 处 理 的 插件 有 : 


rename: 重 命名 某 个 字段 ， 如 果 目 的 字段 已 经 存在 ， 会 被 覆盖 掉 ， 如 下 所 示 : 


filter ( 
mutate ( 
rename —» [ "syslog host" , "host" ] 
} 


update: 更 新 某 个 字段 的 内 容 。 如 果 字 段 不 存在 ， 不 会 新 建 。 
“ replace: 作用 和 update 类 似 ， 但 是 当 字 段 不 存在 的 时 候 ， 它 会 起 到 add_field 参 数 一 样 的 效果 ， 自 动 添加 新 的 字段 。 
4 执行 次 序 


需要 注意 的 是 ，filter/mutate 内 部 是 有 执行 次 序 的 。 其 次 序 如 下 : 


rename (event) if @rename 
update (event) if update 
replace (event) if replace 
convert (event) if convert 
gsub (event) if G8gsub 
uppercase (event) if Guppercase 
lowercase (event) if @lowercase 
strip (event) if @strip 

remove (event) if G8remove 
Split (event) if @split 

join (event) if join 

merge (event) if (merge 

filter matched (event) 


而 filter matched 这 个 fitersbase.rb 里 继承 的 方法 也 是 有 次 序 的 : 


eadd field.each do |field, value| 
end ` 

Gremove field.each do |field| 
end 

Gadd tag.each do |tagl 

ern 

Gremove tag.each do |tag| 

end 


2.3.8 随心所欲 的 Ruby 处 理 


如 果 你 稍微 袋 那么 一 点 点 Ruby 语 法 的 话 ，logstash-filter-ruby 插 件 将 会 是 一 个 非常 有 用 的 工具 。 比 如 你 需要 稍微 修改 一 下 LogStash: : Event 对 象 ， 但 是 又 不 打算 为 此 写 一 个 完整 的 插件 ， 用 
logstash-fitter-ruby 插 件 绝对 感觉 良好 。 


配置 示例 如 下 : 
filter { 
ruby { 
init => “@kname = ['client', 'servername', 'url','status', 'time', 'size', 'upstream', 
'upstreamstatus', 'upstreamtime', 'referer', 'xff', 'useragent']" 
code => *"event.append (Hash [@kname.zip (event['message'].split ( ‘I° ) ) 1)” 


官网 示例 是 一 个 比较 有 趣 但 是 没 哈 大 用 的 做 法 一 一 随机 取消 90% 的 事件 。 


所 以 上 面 我 们 给 出 了 一 个 有 用 而 且 强 大 的 实例 。 


通常 我 们 都 是 用 logstash-filter-grok 揪 件 来 捕获 字段 的 ， 但 是 正则 耗费 大 量 的 CPU 资 源 ， 很 容易 成 为 Logstash 进 程 的 瓶颈 。 


而 实际 上 ， 很 多 流 经 Logstash 的 数据 都 是 有 自己 预定 义 的 特殊 分 隔 符 的 ， 我 们 可 以 很 简单 的 直接 切割 成 多 个 字段 。 


logstash-filter-mutate 插 件 里 的 “split” 选 项 只 能 切 成 数组 ， 后 续 很 不 方便 使 用 和 识别 。 而 在 logstash-filter-ruby 里 ， 我 们 可 以 通过 “init” 参 数 预 定义 好 由 每 个 新 字段 的 名 字 组 成 的 数组 ， 然 后 


ft "code" 参数 指 定 的 Ruby 语 句 里 通过 两 个 数组 的 zip 操 作 生 成 一 个 哈 希 并 添加 进 数组 里 。 短 短 一 行 Ruby 代 码 ， 可 以 减少 50% 以 上 的 CPU 使 用 率 。 


logstash-filter-ruby 揪 件 用 途 远 不 止 这 一 点 ， 下 一 节 你 还 会 继续 见 到 它 的 身影 。 


更 多 实例 如 下 : 


filter( 
date { 
match => [ “datetime , “UNIX” ] 
i 
ruby { 
code => "event.cancel if 5 * 24 * 3600 < (event['Gtimestamp']-::Time.now) . abs" 
} 


在 实际 运用 中 ， 我 们 几乎 肯定 会 碰 到 出 平 意料 的 输入 数据 。 这 都 有 可 能 导致 Elasticsearch 集 群 出 现 问题 。 


当 数 据 格式 发 生变 化 ， 比 如 UNIX 时 间 格 式 变 成 UNIX_MS 时 间 格 式 ， 会 导致 Logstash 疯 狂 创建 新 索引 


, REFR. 


或 者 误 输 入 过 老 的 数据 时 ， 因 为 一 般 我 们 会 close 几 天 之 前 的 索引 以 节省 内 存 ， 必 要 时 再 打开 。 而 直接 烷 试 把 数据 写 入 被 关闭 的 索引 会 导致 内 存 问题 。 


这 时 候 我 们 就 需要 提前 校 验 数据 的 合法 性 。 上 面 配置 ， 就 是 用 于 过 滤 掉 时 间 范 围 与 当前 时 间 差 距 太 大 的 非法 数据 的 。 


2.3.9 split 拆 分 事件 


上 一 章 我 们 通过 multiline 插 件 将 多 行 数据 合并 进 一 个 


jiin} 


配置 示例 如 下 : 


有 件 里 ， 那 么 反 过 来 ， 也 可 以 把 一 行 数据 ， 拆 分 成 多 个 导 


sF. 这 就 是 split 插 件 。 


filter { 
split { 
field => “message” 
terminator => "4" 


} 


这 个 测试 中 ， 我 们 在 intputs/stdin 的 终端 中 输入 一 行 数据 : “test1#test2” ， 结 果 看 到 输出 两 个 事件 : 


"Qversion" : “1” , “@timestamp” : ^"2014-11-18T08:11:33.0002" , "host" : “web121.mweibo.tc.sinanode.com” , "message" : “test1” 


"Qversion" : “1” , "QGtimestamp' : ^"2014-11-18T08:11:33.0002" , “host” : ^"webl21.mweibo.tc.sinanode.com' , "message" : “test2” 


Qus 


split 播 件 中 使 用 的 是 yield 功 能 ， 其 结果 是 split 出 来 的 新 事件 ， 会 直接 结束 其 在 filter 阶 段 的 历程 ， 也 就 是 说 写 在 split 后 面 的 其 他 fltet 揪 件 都 不 起 作用 ， 进 入 到 output 阶 段 。 所 以 ， 一 定 要 保证 split 配 置 写 在 全 


部 fltet 配 置 的 最 后 。 


使 用 了 类 似 功能 的 还 有 clone 插 件 。 从 logstash-1.5.0betal 版 本 以 后 修复 该 问题 。 


2.3.10 elapsed 


Splunk 有 一 项 非常 有 用 的 功能 ， 叫 做 transaction。 可 以 在 错乱 的 多 行 日 志 中 ， 根 据 connected 字 段 、maxspan 窗 


W: http;//docs.splunk.com/Documentation/Splunk/latest/SearchReference/Transaction 


ELK 中 ， 承 载 计算 功能 的 Elasticsearch 并 不 支持 这 种 跨行 计算 ， 所 以 ， 变 通 的 处 理 方式 是 : 在 Logstash 中 ， 提 前 做 好 本 


比如 一 个 transaction task id startswith=START endwith=END 的 查询 ， 可 以 在 Logstash 中 这 样 计算 : 


filter { 


grok { 
match => [ "message" , “%{TIMESTAMP ISO8601} START id: (? «task id».*) " ] 
add tag => [ "taskStarted' ] 

} 

grok { 
match => [ “message” , “%{TIMESTAMP ISO8601} END id: (? <task_id>.*) ” ] 
add tag => [ "taskTerminated" ] 

} 

elapsed { 


start tag => "taskStarted" 
end tag => "taskTerminated" 
unique id field => "task id" 
l 
} 


、 startswith/endwith 标 签 等 信息 计算 出 事件 的 duration 和 count 结 果 。 其 文档 


有 件 的 归并 ， 直 接 计算 出 来 transaction 的 duration 数 据 。 


24 输出 插件 


2.4.1 输出 到 Elasticsearch 


Logstash 早 期 有 三 个 不 同 的 Elasticsearch 播 件 。 到 1.4.0 版 本 的 时 候 ， 开 发 者 彻底 重 写 了 LogSstash: : Outputs: : Elasticsearch 揪 件 。 从 此 ， 我 们 只 需 


Elasticsearch 集 群 支持 的 各 种 不 同 协议 了 。 


1. 配 置 示例 


这 一 个 插件 ， 就 能 任意 切换 使 


output ( 
elasticsearch ( 
host => "192.168.0.2" 
protocol => "http" 
index => "logstash-$ (type]-$ («YYYY .MM. dd)" 
index type => "$(type) 
workers => 5 


template overwrite -» true 


2.88 RE 


“索引 名 ” 写 入 的 Elasticsearch 索 引 的 名 称 ， 这 里 可 以 使 用 变量 。 为 了 更 贴 合 日 志 场 景 ，Logstash 提 供 了 %{+YYYY.MM.dd} 这 种 写法 。 在 语法 解析 的 时 候 ， 看 到 以 + 号 开头 的 ， 就 会 自动 认为 后 面 是 时 间 格 
式 ， 尝 试用 时 间 格 式 来 解析 后 续 字 符 囊 。 所 以 ， 之 前 处 理 过 程 中 不 要 给 自 定义 字段 取 个 加 号 开头 的 名 字 …… 


此 外 ， 注 意 索 引 名 中 不 能 有 大 写字 母 ， 否 则 Elasticsearch 在 日 志 中 会 报 InvalidiIndex-NameException， 但 是 Logstash 不 会 报错 ， 这 个 错误 比较 隐 星 ， 也 容易 掉 进 这 个 坑 中 。 


“协议 现在 ， 新 插件 支持 三 种 协议 : node、http 和 transport。 


一 个 小 集群 里 ， 使 用 node 协 议 最 方便 了 。Logstash 以 Elasticsearch 的 client 节 点 身份 〈 即 不 存 数据 不 参加 选举 ) 运行 。 如 果 你 运行 下 面 这 行 命令 ， 你 就 可 以 看 到 自己 的 Logstash 进 程 名 ， 对 应 的 
node.role 值 是 c: 


# curl 127.0.0.1:9200/ cat/nodes?v 


host ip heap.percent ram.percent load node.role master name 
local 192.168.0.102 7 c = logstash-local-1036-2012 
local 192.168.0.2 7 d * Sunstreak 


特别 的 ， 作 为 一 个 快速 运行 示例 的 需要 ， 你 还 可 以 在 Logstash 进 程 内 部 运行 一 个 内 谋 的 Elasticsearch 服 务 器 。 内 嵌 服 务 器 默认 会 在 $4PWD/data 目 录 里 存储 索引 。 如 果 你 想 变更 这 些 配置 ， 在 
$PWD/elasticsearch.yml 文 件 里 写 自 定义 配置 即 可 ，Logstash 会 尝试 自动 加 载 这 个 文件 。 


对 于 拥有 很 多 索引 的 大 集群 ， 你 可 以 用 transport 协 议 。Logstash 进 程 会 转发 所 有 数据 到 你 指定 的 某 台 主 机 上 。 这 种 协议 跟 上 面 的 node 协 议 是 不 同 的 。node 协 议 下 的 进程 是 可 以 接收 到 整个 
Elasticsearch 集 群 状态 信息 的 ， 当 进程 收 到 一 个 事件 时 ， 它 就 知道 这 个 事件 应 该 存在 集群 内 哪个 机 器 的 分 片 里 ， 所 以 它 就 会 直接 连接 该 机 器 发 送 这 条 数据 。 而 transport 协 议 下 的 进程 不 会 保存 这 个 信息 ， 在 
集群 状态 更 新 (节点 变化 ， 索 引 变 化 都 会 发 送 全 量 更 新 ) 时 ， 就 不 会 对 所 有 的 Logstash 进 程 也 发 送 这 种 信息 。 更 多 Elasticsearch 集 群 状态 的 细节 ， 参 阅 http://www.elasticsearch.org/guide。 


如 果 你 已 经 有 现成 的 Elasticsearch 集 群 ， 但 是 版 本 跟 Logstash 自 带 的 又 不 太一 样 ， 建 议 你 使 用 http 协 议 。Logstash 会 使 用 POST 方式 发 送 数据 。 


3.protocol 选 择 建议 


Logstash 1.4.2 在 transport 和 http 协 议 的 情况 下 是 固定 连接 指定 host 发 送 数据 。 从 1.5.0 开 始 ，host 可 以 设置 数组 ， 它 会 从 节点 列表 中 选取 不 同 的 节点 发 送 数据 ， 达 到 Round-Robin 负 载 均 衡 的 效果 。 


Kibana 4 强制 要 求 Elasticsearch 全 集群 所 有 node 版 本 在 1.4 以 上 ， 所 以 采用 node 方 式 发 送 数据 的 Logstash 1.4 版 (携带 的 Elasticsearch.jar 库 是 1.1.1 版 本 ) 会 导致 Kibana 4 无 法 运行 ， 采 用 Kibana 4 的 
读者 务必 改 用 http 方 式 。 


开发 者 在 IRC freenode#logstash 频 道里 表示 : “高 于 1.0 版 本 的 Elasticsearch 应 该 都 能 跟 最 新 版 Logstash 的 node 协 议 一 起 正常 工作 ”。 此 信息 仅 供 参考 ， 请 认真 测试 后 再 上 线 。 


4. 性 能 问题 


Logstash 1.4.2 在 http 协 议 下 默认 使 用 作者 自己 的 ftw 库 ， 随 同 分 发 的 是 0.0.39 版 。 该 版 本 有 内 存 泄露 问题 ， 长 期 运行 下 输出 性 能 越 来 越 差 ! 


解决 办 法 : 对 性 能 要 求 不 高 的 ， 可 以 在 启动 Logstash 进 程 时， 配置 环境 变量 ENV["BULK"]， 强 制 采用 Elasticsearch 官 方 Ruby 库 。 命 令 如 下 : 


export BULK=“esruby” 


对 性 能 要 求 高 的 ， 可 以 尝试 升级 到 Logstash 1.5 版 。 新 版 的 logstash-output-elasticsearch 放 弃 了 ftw 库 ， 改 用 了 一 个 JRuby 平 台 专 有 的 Manticore 库 。 根 据 测 试 ， 性 能 跟 ftw 比 相当 接近 。 


对 性 能 要 求 极 高 的 ， 可 以 手动 更 新 ftw 库 版 本 ， 目 前 最 新 版 是 0.0.42 版 ， 据 称 内 存 问题 在 0.0.40 版 即 解决 。 


5. 模 板 


Elasticsearch 支 持 给 索引 预定 义 设置 和 mapping (前 提 是 你 用 的 Elasticsearch 版 本 支持 这 个 AP1， 不 过 估计 应 该 都 支持 ) 。Logstash 自 带 有 一 个 优化 好 的 模板 ， 内 容 如 下 : 


{ "template" : “logstash-*” , “settings” : { 'index.refresh interval” : “5s” 
), “mappings” : {“ default " : {“all” : { “enabled” : true], "dynamic templates" : [ ( "string fields" : ( “match” : “+” , "match mapping type" : “string” , "mapping" 
) 
) 
NP ^ « ^ " » « » « " « » « " » » » « » a 
) l], "properties" : ( "éversion' : { “type” : “string”, “index” : "not analyzed' }, “geoip : ( "type" : “object” , "dynamic" : true, “path” : “full” , "properties 
) 
} 
) 
} 
} 
} 
这 其 中 的 关键 设置 包括 : 


* template for index-pattern: 只 有 匹配 logstash-* 的 索引 才 会 应 用 这 个 模板 。 有 时 候 我 们 会 变更 Logstash 的 默认 索引 名 称 ， 记 住 你 也 得 通过 PUT 方 法 上 传 可 以 匹配 你 自 定义 索引 名 的 模板 。 当 然 ， 我 更 建议 的 


做 法 是 ， 把 你 自 定义 的 名 字 放 在 “logstash-” 后 面 ， 变 成 index=>"logstash-custom-%{+yyyy.MM.dd}" 这 样 。 


* refresh. interval for indexing: Elasticseatch 是 一 个 近 实 时 搜索 引擎 。 它 实际 上 是 每 1 秒 钟 刷 新 一 次 数据 。 对 于 日 志 分 析 应 用 ， 我 们 用 不 着 这 么 实时 ， 所 以 Logstash 自 带 的 模板 修改 成 了 5 秒 钟 。 你 还 可 以 根据 
需要 继续 放大 这 个 刷新 间隔 以 提高 数据 写 入 性 能 。 


: multi-field with not analyzed: Elasticsearch 会 自动 使 用 自己 的 默认 分 词 器 (空格 ， 点 ， 和 斜 线 等 分 割 ) 来 分 析 字 段 。 分 词 器 对 于 搜索 和 评分 是 非常 重要 的 ， 但 是 大 大 降低 了 索引 写 入 和 聚合 请 求 的 性 能 。 所 
以 Logstash 模 板 定义 了 一 种 叫 “ 多 字段 ” (multi-field) 类 型 的 字段 。 这 种 类 型 会 自动 添加 一 个 “.rtaw” 结 尾 的 字段 ， 并 给 这 个 字段 设置 为 不 启用 分 词 器 。 简 单 说 ， 你 想 获 取 utl 字 段 的 聚合 结果 的 时 候 ， 不 要 直 


接 用 “ur”， 而 是 用 "urlLraw'" 作 为 字段 名 。 
* geo point: Elasticsearch 支 持 geo_point 类 型 geo distance 聚 合 等 等 。 比 如 说 ， 你 可 以 请 求 某 个 geo_point 点 方圆 10 千 米内 数据 点 的 总 数 。 在 Kibana 的 bettermap 类 型 面板 里 ， 就 会 用 到 这 个 类 型 的 数据 。 
6. 其 他 模板 配置 建议 


“ doc values: doc_values 是 Elasticsearch 1.0 版 本 引入 的 新 特性 。 启 用 该 特性 的 字段 ， 索 引 写 入 的 时 候 会 在 磁盘 上 构建 fielddata。 而 过 去 ，fielddata 是 固定 只 能 使 用 内 存 的 。 在 请 求 范围 加 大 的 时 候 ， 很 容易 
触发 OOM 或 者 citcuit breaker 报 错 : 


ElasticsearchException[org.elasticsearch.common.breaker.CircuitBreakingException: Data too large, data for field [Gtimestamp] would be larger than limit of [639015321/609.4mb]] 


doc values 只 能 给 不 分 词 (对 于 字符 串 字 段 就 是 设置 了 "index": "not analyzed" ， 数 值 和 时 间 字 段 默认 就 没有 分 词 ) 的 字段 配置 生效 。 


doc values 虽 然 用 的 是 磁盘 ， 但 是 系统 本 身 也 有 自 带 VFS 的 cache 效 果 并 不 会 太 差 。 据 官方 测试 ， 经 过 1.4 的 优化 后 ， 只 比 使 用 内 存 的 fielddata 慢 15%。 所 以 ， 在 数据 量 较 大 的 情况 下 ， 强 烈 建议 开启 
配置 : 


对 


{ “template” : “logstash-*” , “settings” : { “index.refresh interval” : “5s” 
), “mappings” : {“ default " : {“all” : { “enabled” : true), "dynamic templates" : [ ( "string fields" : ( "match" "*" , "match mapping type' : “string” , "mapping" 
"doc values" : true } 
) 
) 
} 
) ], “properties” : { “@version” : { “type” : “string” , “index” : "not analyzed” }, “@timestamp” : { “type” : “date, “index” : “not analyzed, “doc values” : tr 
“format” : “dateOptionalTime” }, “geoip? : ( “type : “object” , "dynamic" : true, “path” : “full” , “properties” : { “location” : ( "type" : “geo point" } 


order: 如 果 你 有 自己 单独 定制 template 的 想法 ， 很 好 。 这 时 候 有 几 种 选择 : 
- 在 logstash-output-elasticsearch 配 置 中 开启 manage_template=>false 选 项 ， 然 后 一 切 自己 动手 ; 
- 在 logstash-output-elasticsearch 配 置 中 开启 template=>"/path/to/your/tmpl.json" 选 项 ， 让 ]ogstash 来 发 送 你 自己 写 的 template 文 件 ; 


- 避免 变更 Logstash 里 的 配置 ， 而 是 另外 发 送 一 个 template， 利 用 Elasticsearch 的 templates order 功 能 。 


这 个 order 功 能 ， 就 是 Elasticsearch 在 创建 一 个 索引 的 时 候 ， 如 果 发 现 这 个 索引 同时 匹配 上 了 多 个 template， 那 么 就 会 先 应 用 order 数 值 小 的 template 设 置 ， 然 后 再 应 用 一 遍 order 数 值 高 的 作为 覆盖 ， 
最 终 达到 一 个 merge 的 效果 。 


比如 ， 对 上 面 这 个 模板 已 经 很 满意 ， 只 想 修改 一 下 refresh_interval， 那 么 只 需要 新 写 一 个 : 


{ "order" : 1, "template" : “logstash-*” , “settings” : ( "index.refresh interval” : "20s" 
} 
} 


然后 运行 curl-XPUT http://localhost: 9200/ template/template newid-d'@/path/to/your/tmpl.json' 即 可 。 


Logstash 默 认 的 模板 ，order 是 0，id 是 logstash， 通 过 logstash-output-elasticsearch 的 配置 选项 template_name 修 改 。 你 的 新 模板 就 不 要 跟 这 个 名 字 冲 突 了 。 


2.4.2 发送 email 


配置 示例 如 下 : 


output { 
email { 
to => “admin@website.com, root@website.com” 
cc => “other@website.com’ 
via => “smtp” 
subject => "Warning: %{title}” 
options => ( 


smtpIporHost => "localhost" , 

port => 25, 

domain => 'localhost.localdomain', 

userName => nil, 

password => nil, 

authenticationType => nil, # (plain, login and cram md5) 
starttls => true 


} 

htmlbody => 
body => “” 
attachments => [ “/path/to/filename” ] 


logstash-output-email 插 件 支持 SMTP 协 议和 sendmail 两 种 方式 ， 通 过 via 参 数 设置 。SMTP 方 式 有 较 多 的 options 参 数 可 配置 。sendmail 只 能 利用 本 机 上 的 sendmail 服 务 来 完成 一 一 文档 上 描述 了 
Mail 库 支持 的 sendmail 配 置 参 数 ， 但 实际 代码 中 没有 相关 处 理 ， 不 要 被 迷惑 了 。 


2.4.3 ”调用 系统 命令 执行 


logstash-output-exec 插 件 的 运用 也 非常 简单 ， 如 下 所 示 ， 将 Logstash 切 割 成 的 内 容 作 为 参数 传递 给 命令 。 这 样 ， 在 每 个 事件 到 达 该 插件 的 时 候 ， 都 会 触发 这 个 命令 的 执行 。 


output ( 
exec ( 
command => "sendsms.pl V' $(message]N “ -t $(user)" 


} 


需要 注意 的 是 。 这 种 方式 是 每 次 都 重新 开始 执行 一 次 命令 并 退出 。 本 身 是 比较 慢 速 的 处 理 方式 (程序 加 载 ， 网 络 建 联 等 都 有 一 定 的 时 间 消 耗 ) 。 最 好 只 用 于 少量 的 信息 处 理 场景 ， 比 如 不 适用 nagios 的 
其 他 报警 方式 。 示 例 就 是 通过 短信 发 送 消息 。 


244 保存 成 文件 


通过 日 志 收 集 系 统 将 分 散在 数 百 台 服 务 器 上 的 数据 集中 存储 在 某 中 心服 务 器 上 ， 这 是 运 维 最 原始 的 需求 。 早 年 的 scribed， 甚 至 直接 就 把 输出 的 语法 命名 为 <store>。Logstash 当 然 也 能 做 到 这 点 。 


和 LogStash: : Inputs: : File 不 同 ，LogStash: : Outputs: : File 里 可 以 使 用 sprintf format 格 式 来 自动 定义 输出 到 带 日 期 命名 的 路 径 。 


配置 示例 如 下 : 


output { 
file { 
path => “/path/to/%{+yyyy/MM/dd/HH}/%{host}.log.gz” 


message format => "$(message]" 
gzip — true 


l 


使 用 output/file 插 件 首先 需要 注意 的 就 是 message_format 参 数 。 插 件 默认 是 输出 整个 event 的 JSON 形 式 数据 的 。 这 可 能 跟 大 多 数 情况 下 使 用 者 的 期 望 不 符 。 大 家 可 能 只 是 希望 按照 日 志 的 原始 格式 保 
存 就 好 了 。 所 以 需要 定义 为 %{message}， 当 然 ， 前 提 是 在 之 前 的 filter 播 件 中 ， 你 没有 使 用 remove field 或 者 update 等 参数 删除 或 修改 %{message} 字 有 段 的 内 容 。 


另 一 个 非常 有 用 的 参数 是 gzip。gzip 格 式 是 一 个 非常 奇特 而 友好 的 格式 。 其 格式 包括 有 : 


“ 10 字 节 的 头 ， 包 含 幻 数 、 版 本 号 以 及 时 间 惟 。 


“ 可 选 的 扩展 头 ， 如 原文 件 名 。 


“ 文件 体 ， 包 括 DEFLATE 压 缩 的 数据 。 


“ 8 字 节 的 尾 注 ， 包 括 CRC-32 校 验 和 以 及 未 压缩 的 原始 数据 长 度 。 


这 样 gzip 就 可 以 一 段 一 段 的 识别 出 来 数据 一 一 反 过 来 说 ， 也 就 是 可 以 一 段 一 段 压缩 了 添加 在 后 面 ! 


这 对 于 我 们 流 式 添加 数据 简直 太 棒 了 1! 


Oez 


你 或 许 见 过 网 络 流传 的 parallel 命 令 行 工具 并 发 处 理 数据 的 神奇 文档 ， 但 在 自己 用 的 时 候 总 见 不 到 效果 。 实 际 上 就 是 因为 : 文档 中 处 理 的 gzip 文 件 ， 可 以 分 开 处 理 然后 再 合并 的 ， 而 你 的 用 法 却 不 一 定 可 
以 。 


24.5 ”报警 发 送 到 Nagios 


Logstash 中 有 两 个 output 插 件 是 与 Nagios 有 关 的 。logstash-output-nagios 插 件 发 送 数 据 给 本 机 的 nagios.cmd 管 道 命令 文件 ，logstash-output-nagios_nsca 插 件 则 是 调用 send_nsca 命 令 以 NSCA 
协议 格式 把 数据 发 送 给 Nagios 服 务 器 〈( 远 端 或 者 本 地 皆 可 ) 。 


1.nagios.cmd 


nagios.cmd 是 Nagios 服 务 器 的 核心 组 件 。Nagios 事 件 处 理 和 内 外 交互 都 是 通过 这 个 管道 文件 来 完成 的 。 


使 用 CMD 方 式 ， 需 要 自己 保证 发 送 的 Logstash 事 件 符合 Nagios 事 件 的 格式 。 即 必须 在 filter 阶 段 预先 准备 好 nagios_host 和 nagios_service 字 段 ; 此 外 ， 如 果 在 filter 阶 段 也 准备 好 nagios_annotation 和 
nagios level 字段， 这 里 也 会 自动 转换 成 nagios 事 件 信息 。 


filter ( 
if [message] =~ /err/ { 
mutate ( 
add tag => "nagios" 
rename => [ "host" t “nagios | host” ] 
replace => [ "nagios service" , “logstash check %{type}” ] 
} 
} 
} 
output ( 


if “nagios” in [tags] { 
nagios ( ) 


如 果 不 打算 在 filter 阶 段 提供 nagios_ level， 那 么 也 可 以 在 该 插件 中 通过 参数 配置 。 


所 谓 nagios level， 即 我 们 通过 nagiosplugin 检 查 数据 时 的 返回 值 。 其 取 值 范围 和 含义 如 下 : 


“0”， 代 表 “OK”， 服 务 正常 。 

“1”， 代 表 “WARNNING”， 服 务 警 告 ， 一 般 nagios plugin 命 令 中 使 用 -w 参 数 设置 该 阅 值 。 
"2" , 代表 “CRITICAL”， 服 务 危 急 ， 一 般 nagios plugin 命 令 中 使 用 -c 参 数 设置 该 阅 值 。 
“3”， 代 表 “UNKNOWN”， 未 知 状态 ， 一 般 会 在 timeout 等 情况 下 出 现 。 


默认 情况 下 ， 该 插件 会 以 “CRITICAL” 等 级 发 送 报警 给 Nagios 服 务 器 。 


nagios.cmd 文 件 的 具体 位 置 ， 可 以 使 用 command file 参 数 设置 。 默 认 位 置 是 “/var/lib/nagios3/rw/nagios.cmd"” 


关于 和 nagios.cmd 交 互 的 具体 协议 说 明 ， 有 兴趣 的 读者 请 阅读 Using external commands in Nagios 一 文 (http://archiveO9.linux.com/feature/153285) ， 这 是 《Learning Nagios 3.0》 书 中 内 容 
节选 。 


2.NSCA 


NSCA 是 一 种 标准 的 Nagios 分 布 式 扩展 协议 。 分 布 在 各 机 器 上 的 send_nsca 进 程 主动 将 监控 数据 推送 给 远 端 Nagios 服 务 器 的 NSCA 进 程 。 


当 Logstash 跟 Nagios 服 务 器 没有 在 同一 个 主机 上 运行 的 时 候 ， 就 只 能 通过 NSCA 方 式 来 发 送 报警 了 一 一 当然 也 必须 在 Logstash 服 务 器 上 安装 send_nsca 命 令 


Nagios 事 件 所 需要 的 几 个 属性 在 上 一 段 中 已 经 有 过 描述 。 不 过 在 使 用 这 个 插件 的 时 候 ， 不 要 求 提前 准备 好 ， 而 是 可 以 在 该 插件 内 部 定义 参数 : 


output { 
nagios 1 nsca ( 
nagios | host => “$ s{host}” 
nagios service => "logstash check $(type)" 
nagios status => "2" 
message format => "s(Gtimestamp]: $ (message] " 
host => "nagiosserver.domain.com" 


这 里 请 注意 ，host 和 nagios_host 两 个 参数 ,分别 是 用 来 设置 Nagios 服 务 器 的 地 址 ， 和 报警 信息 中 有 问题 的 服务 器 地 址 。 


关于 NSCA 原 理 ， 架 构 和 配置 说 明 ， 还 不 了 解 的 读者 请 阅读 官方 网 站 Using NSClient+ +from nagios with NSCA 一 节 (http://nsclient.org/nscp/wiki/doc/usage/nagios/nsca) 。 


3. 其 他 类 似 插件 


除了 Nagios 以 外 ，Logstash 同 样 可 以 发 送信 息 给 其 他 常见 监控 系统 ， 方 式 和 Nagios 大 同 小 异 : 
* logstash-output-ganglia 揪 件 通过 UDP 协议 ， 发 送 gmettic 型 数据 给 本 机 / 远 端的 gmond 或 者 gmetad。 


"logstash-output-zabbix 播 件 调用 本 机 的 zabbix_sender 命 令 发 送 。 


2.4.6 statsd 


statsd 最 早 是 2008 年 Flickr 公 司 用 Perl 写 的 针对 graphite、datadog 等 监控 数据 后 端 存储 开发 的 前 端 网 络 应 用 ，2011 年 Etsy 公 司 用 Nodejs 重 构 。 用 于 接收 、 写 入 、 读 取 和 聚合 时 间 序 列 数据 ， 包 括 即 时 
值 和 累积 值 等 。 


配置 示例 如 下 : 


output { 
statsd { 
host => "statsdserver.domain.com" 
namespace => "logstash" 
sender => "$(host])" 
increment => [ "httpd.response.$(status]" ] 


Graphite 以 树 状 结构 存储 监控 数据 ， 所 以 statsd 也 是 如 此 。 所 以 发 送 给 statsd 的 数据 的 key 也 一 定 得 是 “first.second.tree.four” 这样 的 形式 。 而 在 logstash-output-statsd 插 件 中 ， 就 会 以 三 个 配置 参 
数 来 拼接 成 这 种 形式 : 


namespace.sender.metric 


其 中 namespace 和 sender 都 是 直接 设置 的 ， 而 metric 又 分 为 好 几 个 不 同 的 参数 可 以 分 别 设置 。statsd 支 持 的 metric 类 型 如 下 : 


* increment 


示例 语法 : increment=>["nginx.status.9%{status}"]。 该 配置 即 可 在 statsd 中 生成 对 应 的 
nginx.status.200，nginx.status.206，nginx.status.304，nginx.status.404，nginx.status.502，nginx.status.503，nginx.status.504 等 一 系列 监控 项 。 同 时 ， 在 statsd 内 配置 的 一 个 时 间 周 期 内 ， 各 状态 
码 的 次 数 ， 会 自动 累加 到 各 自 监控 项 里 。 


* decrement 


语法 同 increment。 不 过 是 递减 而 不 是 递增 。 


* count 


dit 
Bl 


示例 语法 : count-»("nginx.bytes" -» "9%{bytes}"}。 该 配置 可 以 在 statsd 中 生成 一 个 nginx.bytes 监 控 项 。 而 每 条 Nginx 访 问 记 录 的 响应 字 节 数 ， 累 加 成 下 
` gauge 


语法 同 count。gauge 和 count (在 rrdtool 中 叫 counter) 两 种 计数 器 的 区 别 从 早年 的 rrdtool 时 代 就 被 反复 强调 ， 即 gauge 直 接 存储 原始 数值 ， 不 累加 。 


* set 


示例 语法 : set=>{"online"=>"%{user_id}"}。 是 新 版 statsd 才 支持 的 功能 ， 可 以 用 来 做 去 重 计算 ， 比 如 在 线 人 数 统 计 。 
- timing 


示例 语法 : timing=>["nginx.requesttime"=> "9%{request timej"]。 该 配置 可 以 在 statsd 中 生成 一 个 nginx.requesttime 监 控 项 ， 记 录 时 间 周 期 内 ，Nginx 访 问 记 录 的 响应 时 间 的 数值 统计 情况 ， 包 括 
平均 值 ， 最 大 值 ， 最 小 值 ， 标 准 差 ， 百 分 比值 等 。 


关于 这 些 metric 类 型 的 详细 说 明 ， 请 阅读 statsd 文 档 : https;//github.com/etsy/statsd/blob/master/docs/metric types.md, 


推荐 阅读 
Etsy 发 布 hodejs 版 本 statsd 的 博客 : Measure Anything, Measure Everything (http:/ /codeascraft.etsy.com/2011/02/15/measure-anything-measure-everything/) 
Flickr 发 布 statsd 的 博客 : Counting&Timing (http://code.flickr.net/2008/10/27/counting-timing/) 


Librato 有 关 statsd 协 作 的 博客 : Using StatsD with Librato (http://support.metrics.librato.com/knowledgebase /articles/77199-using-statsd-with-librato) 


24.7 ”标准 输出 stdout 


和 之 前 logstash-input-stdin 插 件 一 样 ，logstash-output-stdout 插 件 也 是 最 基础 和 简单 的 输出 插件 。 同 样 在 这 里 简单 介绍 一 下 ， 作 为 输出 插件 的 一 个 共性 了 解 。 


配置 示例 如 下 : 


output { 
stdout { 
codec => rubydebug 
workers => 2 


} 


输出 插件 统一 具有 一 个 参数 是 workers。Logstash 为 输出 做 了 多 线程 的 准备 。 


其 次 是 codec 设 置 。codec 的 作用 在 之 前 已 经 讲 过 。 可 能 除了 logstash-codec-multiline， 其 他 codec 插 件 本 身 并 没有 太 多 的 设置 项 。 所 以 一 般 省 略 掉 后 面 的 配置 区 段 。 换 句 话说 。 上 面 配置 示例 的 完全 
写法 应 该 是 : 


output ( 
stdout ( 
codec -» rubydebug ( 
} 


workers => 2 


单 就 logstash-output-stdout 插 件 来 说 ， 其 最 重要 和 常见 的 用 途 就 是 调试 。 所 以 在 不 太 有 效 的 时 候 ， 加 上 命令 行 参 数 -vv 运行 ， 查 看 更 多 详细 调试 信息 。 


24.8 TCP 发 送 数 据 


虽然 之 前 我 们 已 经 提 到 过 不 建议 直接 使 用 Logstash: : Inputs: : TCP 和 LogStash: : Outputs: : TCP 做 转发 工作 ， 不 过 在 实际 交流 中 ， 发 现 确实 有 不 少 朋 友 觉 得 这 种 简单 配置 足够 使 用 ， 因 而 不 愿 
意 多 加 一 层 消息 队列 的 。 所 以 ， 还 是 把 Logstash 如 何 直接 发 送 TCP 数 据 也 稍微 提 点 一 下 。 


配置 示例 如 下 : 


output { 
tcp { 
host => “192.168.0.2” 
port => 8888 
codec => json lines 


} 


在 收集 端 采 用 TCP 方 式 发 送 给 远 端 的 TCP 端 口 。 这 里 需要 注意 的 是 ， 默 认 的 Codec 选 项 是 json。 而 远 端 的 LogStash: : Inputs: : TCP 的 默认 Codec 选 项 却 是 plain! 所 以 不 指定 各 自 的 Codec， 对 接 肯 
定 是 失败 的 。 


另外 ， 由 于 IO BUFFER 的 原因 ， 即 使 是 两 端 共 同 约定 为 json 依 然 无 法 正常 运行 ， 接 收 端 会 认为 一 行 数据 没 结束 ， 一 直 等 待 直至 自己 OutOfMemory! 


所 以 ， 正 确 的 做 法 是 ， 发 送 端 指定 Codec 为 json_lines， 这 样 每 条 数据 后 面 会 加 上 一 个 回 车 ,接收 端 指定 Codec 为 json_lines 或 者 json 均 可 ， 这 样 才能 正常 处 理 。 包 括 在 收集 端 已 经 切割 好 的 字段 ， 也 可 
以 直接 带 入 收集 端 使 用 了 。 


2.4.9 ”输出 到 HDFS 


数据 写 入 HDFS 是 很 多 日 志 收 集 系统 的 最 终 目 的 。 不 过 Logstash 偏 巧 不 是 其 中 之 一 。 到 目前 为 止 ，Logstash 还 没有 官方 支持 的 直接 写 入 HDFS 的 插件 。 而 在 社区 ， 则 有 两 种 不 同 的 解决 方案 可 供 选 择 。 下 


面 分 别 介绍 。 


1. 通 过 HTTP 接 口 


插件 源码 地 址 见 : https;//github.com/dstore-dbap/logstash-webhdfs 


该 插件 使 用 Hadoop 的 WebHDFS 接 口 ， 其 本 质 就 是 发 送 POST 数 据 ， 可 以 说 实现 起 来 比较 简单 。 未 来 logstash-plugins 官 方 可 能 也 会 收 这 个 插件 。 


配置 示例 如 下 : 


output { 

hadoop webhdfs { 
workers => 2 
server => "your.nameno.de:14000" 
user => “flume” 
path => “/user/flume/logstash/dt=%{+Y}-%{+M}-%{+d}/logstash-%{+H}.log” 
f?lush_size => 500 
compress => “snappy” 
idle f?lush time => 10 
retry interval => 0.5 


播 件 使 用 方式 ， 和 其 他 自 定义 插件 一 样 ， 通 过 一 pluginpath 或 者 打包 gem 均 可 。 


2. 通 过 Java 接 


播 件 源码 地 址 见 : https:;//github.com/avishai-ish-shalom/logstash-hdfs 


该 插件 使 用 Hadoop 的 HDFS 接 口 ， 利 用 JRuby 可 以 直接 导入 Java 类 的 特性 ， 直 接 使 用 了 org.apache.hadoop.fs.FileSystem 等 类 来 实现 。 


配置 示例 如 下 : 


output { 
hdfs ( 
path => "/path/to/output file.log" 
enable append => true 一 
} 


因为 需要 导入 各 种 Hadoop 的 jar 包 ， 所 以 这 个 运行 比较 麻烦 。Logstash-1.4.2 上 的 运行 命令 示例 如 下 : 


* LD LIBRARY PATH- "/usr/lib/hadoop/lib/native" GEM HOME-./logstash-1.4.2/vendor/bundle/jruby/1.9 CLASSPATH-$ (find ./logstash-1.4.2/vendor/jar -type f -name '*.jar'|tr '\n' ': 


如 果 使 用 Logstash-1.5 版 本 ， 可 以 通过 rubygems.org 直 接 安装 打包 好 的 插件 : 


# bin/plugin install logstash-output-hdfs 


* LD LIBRARY PATH- "/usr/lib/hadoop/lib/native" CLASSPATH-$ (find /usr/lib/hadoop-hdfs -type f -name '*.jar' | tr '\n' ': ') : $ (find /usr/lib/hadoop -type f -name '*.jar' | gi 


第 3 章 场景 示例 


前 面 虽然 介绍 了 几 十 个 Logstash 揪 件 的 常见 配置 项 ， 但 是 过 多 的 选择 下 ， 如 何 组 合 使 用 这 些 插 件 ， 依 然 是 一 部 分 用 户 的 难题 。 本 章 将 列举 一 些 最 常见 的 日 志 场 景 ， 演 示 针对 性 的 组 件 搭配 ， 希 望 能 给 读 
节 来 启发 。 


者 


E 


本 章 介绍 的 场景 包括 : Nginx 访 问 日 志 、Nginx 错 误 日 志 、Postfix 日 志 、Ossec 日 志 、Windows 系 统 日 志 、Java 


志 、MySQL 慢 查询 日 志 、Docker 容 器 日 志 。 


3.1 Nginx 访 问 日 志 


访问 日 志 处 理 分 析 绝 对 是 使 用 ELK stack 时 最 常见 的 需求 。 默 认 的 处 理 方式 下 ， 性 能 和 精确 度 都 不 够 好 。 本 节 会 列举 对 Nginx 访 问 日 志 的 几 种 不 同 处 理 方式 ， 并 阐明 其 优 劣 。 


3.1.1 grok 处 理 方式 


Logstash 默 认 自 带 了 Apache 标 准 日 志 的 grok 正 则 : 


COMMONAPACHELOG % SUTPORHOST: clientip) $(USER:ident) $(NOTSPACE:auth)N [$(HTTPDATE: 
timestamp)N Qui WORD: verb) $(NOTSPACE: request] (? : HTTP/S(NUMBER:httpversion)) ? 
|*$(DATA:rawrequest]) " $(NUMBER:response] (? : $(NUMBER:bytes) |-) 


COMBINEDAPACHELOG $(COMMONAPACHELOG] $(QS:referrer] $(QS:agent] 


对 于 Nginx 标 准 日 志 格式 ， 可 以 发 现 只 是 最 后 多 了 一 个 $http_x_forwarded for 变 量 。 所 以 Nginx 标 准 日 志 的 grok 正 则 定义 是 : 


MAINNGINXLOG $(COMBINEDAPACHELOG] $(QS:x forwarded for] 


自 定义 的 日 志 格式 ， 可 以 照 此 修改 。 


3.1.2 split 处 理 方式 


Nginx 日 志 因 为 部 分 变量 中 内 含 空格 ， 所 以 很 多 时 候 只 能 使 
格式 如 下 : 


%{QS} 正 则 来 做 分 隔 ， 性 能 和 细 度 都 不 太 好 。 如 果 能 自 定义 一 个 比较 少见 的 字符 作为 分 隔 符 ， 那 么 处 理 起 来 就 简单 多 了 。 假 设 定义 的 日 志 


log format main "Shttp ; XC forwarded for | $time local | $request | $status | 


$body bytes sent | *$request body | $content length | $http referer | $http user agent | $nuid | " "$http cookie | $remote addr | $hostname | $upstream addr | $upstream. 
time | $request time" ; 


实际 日 志 如 下 : 


117.136.9.248 | 08/Apr/2015:16:00:01 +0800 | POST /notice/newmessage?sign-cba4f614e05db285850cadc696fcdad0&token-JAGQ92Mjs3--gik b DsPIQHcyMKYGpDádid=b749736ac70f12df700b18cd6c 


然后 还 可 以 针对 request 做 更 细致 的 切 分。 比如 URL 参 数 部 分 。 很 明显 ，URL 参 数 中 的 字段 顺序 是 乱 的。 第 一 行 问号 之 后 的 第 一 个 字段 是 sign， 第 二 行 问 号 之 后 的 第 一 个 字段 是 appv。 所 以 需要 将 字段 进 
行 切 分 ， 取 出 每 个 字段 对 应 的 值 。 官 方 自 带 grok 满 足 不 了 要 求 ， 最 终 采 用 的 Logstash 配 置 如 下 : 


filter ( 
ruby { 
init => "Gkname -[' http x forwarded for', 'time local','request','status', 
'body bytes sent', request body','content length','http referer','http 
user agent','nuid','http cookie','remote addr', 'hostname', 'upstream 
addr", 'upstream response time' 'tequest | time']^ 
code => "event. append (Hash[Gkname. zip (event['message'].split ( | ' ) ) D " 
} 
if [request] { 
ruby { 
init => “@kname = ['method','uri','verb']" 
code => “event.append (Hash [@kname.zip (event['request'].split ( ' ' ) ) ]) 
} 
if [uri] { 
ruby { 
init => “@kname =[' al Fast args ba 
code => "event.append (Hash[@kname.zip (event['request'].split ( '?2 ))])” 
} 
kv ( 
prefix => "url " 
source => T arge" 
field split => "& 
remove field => [ “url_args” , “uri” , “request” ] 
} 
$ 
mutate { 
convert => [ “body bytes sent” , “integer” , “content_length” , “integer” , "upstream response time" , “float” , “request time” , “float” 
] 


l 
date ( 


match => [ "time _ local” , "dd/MMM/yyyy:hh:mm:ss 2” ] 
locale => “en” 


最 终结 果 如 下 : 


{ “message” => “1.43.3.188 | 08/Apr/2015:16:00:01 +0800 | POST /search/sug 
gest?appv=3.0.3&did=dfd5629d705d400795£698055806f01ldgdt=iPhone7%2C2&im= 
AC926907-27AA-4A10-9916-C5DC75F29399&1a-cn&latitude--33.903867&1m- 
sina&longitude-151.208137&1p--1.000000&net-0-0-wifi&osn-iOS&osv-8.1.3&sh-66 
7.000000&sw-375.000000&token- ovaPz6Ue68ybBuhXustPbG-xflWbsPO&ts- 
1428480001567 HTTP/1.1 | 200 | 353 | abcd-sign-vl1://a24b478486d3bb92ed89a- 
9015415b60a5:b23e9d2c14£e6755/ {\\x22key\\x22: \\x22last\\x22, NNx220ff£set NN x22: 
\\x220\\x22, NNx22tokenNNx22:NNx22. ovaPz6Ue68ybBuhXustPbG-xflWbsPOWN x22, 
NAx221imitNNx22:NNx2220NAx22) | 148 | - | abcdShopping/3.0.3 (iPhone; iOS 


8.1.3; Scale/2.00) | nuid-0B0A0A0A9A64AF54F97634640230944E1428480001.113 
| nuid-CgoKC1SvZJpkNHb5TpOwAg-- | 10.10.10.11 | bnx02.abcdprivate.com | 


10.10.10.26:9999 | 0.070 | 0.071” , "Gversion' => “1” , "Gtimestamp' => "2015-04-08T08:00:01.000Z2" , "type" => "nginxapiaccess' , “host” => "blog05. 


4£e6755/ (NNxX22keyNNx22: \\x22last\\x22, \\x220ffset\\x22 : \\x220\\x22, NNx22token 


\\x22:\\x22_ovaPz6Ue68ybBuhXustPbG-xf1WbsPO\\x22, \\x22limit\\x22:\\x2220\\x22}” , “content_length” => 148, "http referer" 


=> 


, "http user agent" 


abcdprivate.com" , "path 


=> "abcdShopping/3.0.3 


如 果 URL 参 数 过 多 ， 可 以 不 使 用 kv 切 分 ,或 者 预先 定义 成 nested object 后 改 成 数组 形式 : 


if [uri] i 
ruby { 
init => “@kname = ['url path','url args']" 
code => "event.append (Hash[G8kname.zip (event['request'].split ( '?2 ) ) 1) " 


} 
if [url_args] { 


ruby { 
init => “@kname = ['key', 'value']” 
code => “event ['nested args'] = event['url args'].split ( '&' ) a collect 
{lil Hash[Gkname.zip (i.split ( ‘= ) ) ])" 
remove field => [ "url args' , “uri” , "request" ] 


} 


采用 nested object 的 优化 原理 和 nested object 的 使 用 方式 ， 请 阅读 后 面 Elasticsearch 调 优 章节 。 


3.1.3 json 格 式 


自 定义 分 隔 符 虽 好 ， 但 是 配置 写 起 来 毕竟 复杂 很 多 。 其 实 对 Logstash 来 说，Nginx 日 志 还 有 另 一 种 更 简便 的 处 理 方式 ， 就 是 自 定义 日 志 格式 时 ， 通 过 手工 拼写 直接 输出 成 JJON 格 式 : 


log format json '( "Gtimestamp' : “$time iso8601' ,' 
B ' “host” : "Sserver addr" ,' 
"clientip' : "$remote addr' ,' 
' "size" :$body bytes sent," 
"responsetime" :$request time, ' 
"upstreamtime' : "$upstream response time" ,' 
"upstreamhost' : "Supstream addr” ,' - 
E "http host" : “$host” ,' 
"url" : "Suri" ,' 
xff' : "Shttp x forwarded for" ,' 
“referer” : "Shttp referer" ,' 
' “agent” : “$http user agent” , 
"status" : "Sstatus" ]'; 


然后 采用 下 面 的 Logstash 配 置 即 可 : 


input ( 
file ( 
path => "/var/log/nginx/access.log" 
codec => json 
} 
} 
filter { 
mutate { 
split => [ "upstreamtime" , ^, 1 
) 
mutate ( 
convert => [ “upstreamtime” , "float" ] 


这 里 采用 多 个 mutate 插 件 ， 是 因为 upstreamtime 可 能 有 多 个 数值 ， 所 以 先 切 割 成 数组 以 后 ， 再 分 别 转换 成 浮 点 型 数值 。 而 在 mutate 中 ，convert 函 数 的 执行 优先 级 高 于 split 函 数 ， 所 以 只 能 分 开 两 步 


写 。mutate 内 各 函数 的 优先 级 顺序 ， 之 前 插件 介绍 章节 有 详细 说 明 ， 读 者 可 以 返回 去 阅读 。 


3.1.4 syslog 方 式 发 送 


Nginx 从 1.7 版 开始 ， 加 入 了 syslog 支 持 ，Tengine 则 更 早 。 这 样 ， 我 们 可 以 通过 syslog 直 接 发 送 日 志 。Nginx 上 的 配置 如 下 : 


access log syslog:server-unix:/data0/rsyslog/nginx.sock locallog; 


或 者 直接 发 送 给 远程 Logstash 机 器 : 


access log syslog:server-192.168.0.2:5140,facility-local6, tag-nginx-access, 
severity-info logstashlog; 


默认 情况 下 ，Nginx 将 使 用 local7.info 等 级 ， 以 nginx 为 标签 发 送 数据 。 注 意 ， 采 用 syslog 发 送 日 志 的 时 候 ， 无 法 配置 buffer= 16k 选 项 。 


32 ”Nginx 错 误 日 志 


Nginx 错 误 日 志 是 运 维 人 员 最 常见 但 又 极其 容易 忽略 的 日 志 类 型 之 一 。 本 节 介绍 对 Nginx 错 误 日 志 的 处 理 方式 ， 并 推荐 读者 在 性 能 优化 中 对 此 多 加 关注 。Nginx 错 误 日 志 既 没有 统一 明确 的 分 隔 符 ， 也 没 


有 特别 方便 的 正则 模式 ， 但 通过 Logstash 不 同 插件 的 组 合 ， 还 是 可 以 轻松 进行 数据 处 理 的 。 


值得 注意 的 是 ，Nginx 错 误 日 志 中 有 一 类 数据 是 接收 过 大 请 求 体 时 的 报错 ， 默 认 信息 会 把 请 求 体 的 具体 字 节 数 记 录 下 来 。 每 次 请 求 的 字 节 数 基本 都 是 在 变化 的 ， 这 意味 着 常 


段 没有 明显 效果 。 所 以 ， 对 此 需要 做 一 下 特殊 处 理 。 


最 后 形成 的 Logstash 配 置 如 下 所 示 : 


filter { 

grok { 

match => ( “message” => " (? <datetime>\d\d\d\d/\d\d/\d\d \d\d:\d\d:\d\d) 

\[ (? <errtype>\w+) \] \S+: \*\d+t (? «errmsg2[^,]4) , (? <errinfo>.*) $” } 

l 
mutate ( 

rename => [ “host” , “fromhost” ] 

gsub => [ “errmsg”, “too large body: \d+ bytes” , “too large body” ] 


if [errinfo] 


{ 


的 topN 等 聚合 函数 对 该 字 


ruby { 


code => "event.append (Hash[event['errinfo'].split ( ', ' ) ə map{|1| l.split 


(0*3 9 
} 
} 
grok ( 
match => ( request" 


=> 
URIPARAM:urlparam}) ? 


* “%{WORD: verb} %{URIPATH:urlpath} (? : M?S(NGX 
(? : HTTP/S$(NUMBER:httpversion]) " ' 


patterns dir => "/etc/logstash/patterns" 
remove field => [ "message" , "errinfo' , “request” ] 


经 过 以 上 Logstash 配 置 的 Nginx 错 误 日 志 生 成 的 事件 如 下 所 示 : 


{ “@version” : “1” , “@timestamp” 


"2015-07-02T01:26:40.000Z" , “type” : “nginx-error” , “errtype” : “error” , “errmsg” : 


XakjUZM5792FW9A5S9EU4jxqQ&wm=3333_2001&i=0c6f156&b=1&from=1053093010&c= 
iphone&v p-21&skin-default&v : f-l&s- 8f14e573&lang-zh í CN&ua-iPhone7,1 weibo . 
5.3.0 iphone os8.3” , "httpversion' : “1.1” 


"client intended to send too large body" 


D 


"fromhost" 


3.3 ”Postfix 日 志 


Postfix 是 Linux 平 台 上 最 常用 的 邮件 服务 器 软件 。 邮 件 服务 的 运 维 复杂 


patterns, 


因为 Postfix 默 认 通过 syslog 方 式 输出 日 


志 ， 所 以 可 以 选择 通过 rsyslog 直 接 转 发 给 Logstash， 也 可 以 由 Logstash 读 取 rsyslog 记 录 的 文件 。 


一 向 较 高 ， 在 此 提供 一 个 针对 Postfix 日 志 的 解析 处 理 方案 。 方 案 出 自 : https://github.com/whyscream/postfix-grok- 


Postfix 会 根据 实际 日 志 的 不 同 ， 主 动 设置 好 不 同 的 syslogtag， 有 anvil、bounce、cleanup、dnsblog、local、master、pickup、pipe、postdrop、postscreen、qmgr、scache、sendmail、 
smtp、Imtp、smtpd、tlsmgr、tlsproxy、trivial-rewrite 和 discard 等 20 个 不 同 的 后 缀 ， 而 在 Logstash 中 ，syslogtag 通 常 被 解析 为 program 字 段 。 本 节 以 第 一 种 anvil 上 日 志 的 处 理 配 置 作为 示例 : 


input { 
syslog ( ) 


$ 
filter { 


if [program] =~ /^postfix.*\/anvil$/ { 


grok { 
patterns dir => 
match => 
tag on failure => 
add | tag => 
} 


l 
mutate ( 
convert => [ 


[ 
[ 
[ 


“/etc/logstash/patterns. d 


"message" PN $(POSTFIX | ANVIL)' ] 
„grok postfix i anvil _nomatch” ] 
”grok postfix : success" ] 


“postfix ; anvil cache . size", “integer” 7 
“postfix anvil conn í count” " “integer” " 
“postfix ， anvil. . conn ; | rate" " "integer" " 


配置 中 使 用 了 一 个 叫 POSTFIX_ANVIL 的 自 定义 grok 正 则 ， 该 正则 及 其 相关 正则 内 容 如 下 所 示 。 将 这 段 grok 正 则 保存 成 文本 文件 ， 放 入 /etc/logstashVpatterns.d/ 目 录 即 可 使 用 。 


POSTFIX TIME UNIT $(NUMBER] [smhd] 


POSTFIX ANVIL CONN RATE statistics: max connection rate $(NUMBER: postfix . anvil conn. 
rate)/*$(POSTFIX TIME UNIT:postfix anvil conn period) for \ (&$(DATA:postfix | 
service):*(IP:postfix client ip)V) at &$(SYSLOGTIMESTAMP: Pie anvil 


timestamp] 


POSTFIX ANVIL CONN CACHE statistics: max cache size $(NUMBER:postfix anvil 
cache | size) at $(SYSLOGTIMESTAMP: postfix anvil timestamp] 
POSTFIX ANVIL , CONN COUNT statistics: max connection count $(NUMBER:postfix | 
anvil . conn | count] for X (S(DATA: postfix service]:$([IP:postfix client Lip) at 
$ (SYSLOGTIMESTAMP: postfix anvil timestamp) 
POSTFIX ANVIL $(POSTFIX ANVIL CONN RATE)|$(POSTFIX ANVIL CONN CACHE)|$(POSTFIX 


ANVIL CONN COUNT) 


3.44 ”Ossec 日 志 


其 余 19 种 Postfix 日 志 的 完整 grok 正 则 和 Logstash 过 滤 配 置 ， 读 者 可 以 通过 https://github.com/whyscream/postfix-grok-patterns 获 取 。 


Osse< 是 一 款 开源 的 多 平台 入 侵 检测 系统 。 将 Ossec 的 监测 报警 信息 转发 到 ELK 中 ， 无 疑 可 以 极 大 地 帮助 我 们 快速 可 视 化 安全 事件 。 本 节 介绍 Ossec 与 Logstash 的 结合 方式 。 


34.1 配置 所 有 Ossec agent 采 用 syslog 输 出 


配置 步骤 如 下 : 


1) 编辑 ossec.conf 文 件 (默认 为 /var/ossec/etc/ossec.conf) 。 


2) 在 ossec.conf 中 添加 下 列 内 容 (10.0.0.1 为 接收 syslog 的 服务 器 ) : 


«syslog output» 
«server»10.0.0.1«/server» 
«port»9000«/port» 
«format»default«/format» 
«/syslog output» 


3) 开启 Ossec 人 允许 syslog 输 出 功能 


/var/ossec/bin/ossec-control enable client-syslog 


4) 重启 Ossec 服 务 : 


/var/ossec/bin/ossec-control start 


3.42. 配置 Logstash 


在 Logstash 配 置 文件 中 增加 (或 新 建 ) 如 下 内 容 (假设 10.0.0.1 为 Elasticsearch 服 务 器 ) : 


input { 


udp ( 
port => 9000 


type => “syslog” 
} 
} 


filter { 
if [type] == “syslog” { 
grok { 
match => { “message” => “%{SYSLOGTIMESTAMP:syslog_timestamp} %{SYSLOGHOST: 
syslog_host} %{DATA:syslog_program}: Alert Level: %{BASE10NUM: 
Alert Level); Rule: %{BASE10NUM:Rule} - %{GREEDYDATA: Description}; 
Location: &(GREEDYDATA:Details])" } 
add field => [ “ossec server" , "$(host)' ] 
mutate ( 
remove field => [ “syslog hostname" , "syslog message" ; '"syslog pid" , 
"message" , "Qversion' , “type”, "host" ] 
} 
} 
} 
output { 


elasticsearch { 


} 


3.4.3 ”推荐 Kibana 仪 表盘 


社 


区 已 经 有 人 根据 Ossec 的 常见 需求 制作 了 仪表 盘 ， 可 以 直接 从 Kibana 3 页 面 加 载 使 用 ， 示 例如 


[R] 


3-1 所 示 。 


仪表 盘 的 JSON 文 件 见 : https://github.com/magenx/Logstash/raw/master/kibana/kibana dash-board.json, 


加 载 方式 请 阅读 本 书 第 三 部 分 Kibana 的 相关 内 容 。 
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图 3-1  OssecBU d 


35 ”Windows 系 统 日 志 


Logstash 社 区 有 众多 的 Windows 用 户 ， 本 节 单 独 介绍 一 下 对 Windows 平 台 系统 日 志 的 收集 处 理 。 之 前 介绍 过 Linux 上 的 系统 日 志 ， 即 syslog 的 处 理 。 事 实 上 ， 对 于 Windows 平 台 ， 也 有 类 似 syslog 的 设 
计 ， 叫 eventlog。 本 节 介绍 如 何 处 理 Windows eventlog。 


3.5.1 “采集 端 配置 


由 于 Logstash 作 者 出 身 Linux 运 维 ， 早 期 版 本 中 出 了 不 少 Windows 平 台 上 独 有 的 bug。 所 以 ， 目 前 对 Windows 上 的 日 志 ， 推 荐 大 家 在 党 试 Logstash 的 同时 ， 也 可 以 试用 更 稳定 的 nxlog 软 件 。nxlog 更 
详细 的 介绍 ， 请 阅读 本 书 稍 后 章节 。 


这 里 先 介绍 Logstash 和 nxlog 在 处 理 Windows 的 eventlog 时 的 配置 方法 。 


Logstash 配 置 如 下 : 


input ( 
eventlog ( 
#logfile => [ “Application” , “Security” , “System” ] 
logfile => [ “Security” ] 
type => “winevent” 
tags => [ “caen” ] 


nxlog 配 置 中 有 如 下 几 个 要 点 : 
1) ROOT 位 置 必须 是 nxlog 的 实际 安装 路 径 。 
2) 输入 模块 ， 在 Windows 2003 及 之 前 版 本 上 ， 不 叫 im_msvistalog 而 叫 im_mseventlog。 


下 面 是 一 段 完 整 的 nxlog 配 置 示例 : 


define ROOT C:\Program Files (x86) \nxlog 
Moduledir %ROOT%\modules 
CacheDir $ROOT$Ndata 
Pidfile $ROOT$Ndata Wxlog.pid 
SpoolDir $ROOT$Ndata 
LogFile %ROOT%\data\nxlog.log 
«Extension json» 
Module xm json 


«/Extension» 
«Input in» 
Module im msvistalog 
Exec to json () ; 
«/Input» 


«Output out» 
Module om tcp 
Host 10.66.66.66 


Port 5140 
«/Output» 
«Route 1» 

Path in => out 
«/Route» 


3.52 ”接收 解析 端 配置 


在 中 心 的 接收 端 ， 统 一 采用 Logstash 来 完成 解析 入 库 操作 。 如 果 采 集 端 也 是 Logstash， 主 要 字段 都 已 经 生成 ， 接 收 端 配置 也 就 没什么 特别 的 了 。 如 果 采 集 端 是 nxlog， 那 么 我 们 还 需要 把 一 些 nxlog 生 成 
的 字段 转换 成 Logstash 更 通用 的 风格 设计 。 


在 之 前 插件 介绍 章节 我 们 已 经 讲 过 ， 因 为 在 Elasticsearch 中 默认 按 小 写 来 检索 ， 所 以 需要 尽量 把 数据 小 写 化 。 不 巧 的 是 ，nxlog 中 ， 不 单数 据 内 容 ， 字 段 名 称 也 是 大 小 写 混用 的 ， 所 以 ,我 们 只 能 通过 


logstash-filter-mutate 的 rename 功 能 来 完成 对 字段 名 称 的 小 写 化 重 命名 。 
配置 示例 如 下 : 
input { 
tcp { 


codec => “json” 
port => 5140 
tags => [ “windows” , “nxlog” ] 
type => “nxlog-json” 
l 
) * end input 


filter ( 
if [type] ==  "nxlog-json' { 
date ( 
match => [ "[EventTime]" , “YYYY-MM-dd HH:mm:ss” ] 
timezone => “Europe/London” 
mutate { 
rename => “AccountName” , "user" ] 
rename => ^AccountType' , “[eventlog] [account typel' ] 
rename —» "ActivityId" , "[eventlog][activity id]" ] 
rename => [ "Address" , ‘ip6” 
rename => "ApplicationPath' , “[eventlog] [application path]" ] 
rename => "AuthenticationPackageName' , “ [eventlog] [authentication package 
name]" ] d 一 
rename => “Category” , "[eventlog][categoryl' ] 
rename => “Channel” , “[eventlog] [channel] 1 
rename => "Domain" , “domain” ] 
rename => “EventID” , "[eventlogllevent id]" ] 
rename => "EventType' , “[eventlog] [event type]" ] 
rename => "File" , "[eventlog [file path]" ] 
rename => “Guid” , "[eventlog] [guid 
rename => “Hostname” , "hostname" 
rename => “Interface” , "[eventlogl[interface]" ] 
rename => "InterfaceGuid' , "[eventlog][interface guid]” ] 
rename => ^InterfaceName' , “[eventlog] [interface name]" ] 
rename => "IpAddress" , “ip” ] T 
rename => “IpPort” , “port” 
rename => "Key" , "[eventlogl[keyl' ] 
rename => "LogonGuid' , ^"[eventlog][logon guid]" ] 
rename => "Message" , “message” ] T 
rename => "ModifyingUser' , “[eventlog] [modifying user]" ] 
rename => "NewProfile" , "[eventlog][new profile]" ] 
rename => "OldProfile" , ^"[eventlog][old profile]" ] 
rename => "Port" , “port” ] 
rename => "PrivilegeList" , “[eventlog] [privilege list]" ] 
rename => "ProcessID' , “pid” ] 
rename => "ProcessName" , ^"[eventlog][process name]" 


rename => "ProviderGuid" r “ [eventlog] [provider « guid]" ] 
rename => "ReasonCode' , "[eventlog] [reason code]" ] 
rename => "RecordNumber" "nu “ [eventlog] [record 1 number]" ] 
rename => "ScenarioId" , "[eventlog] [scenario id]" ] 
rename => "Severity' , "level" ] 
rename —» "SeverityValue" , "[eventlog] [severity « codel' ] 
rename => "SourceModuleName" , "nxlog . input' ] 
rename => "SourceName" , "[eventlog][program]" 
rename —» "SubjectDomainName" 1 “ [event1og] [subject « domain | name]" ] 
rename => "SubjectLogonld' , "[eventlog] [subject logonid]" ] 
rename => “SubjectUserName” 。 [eventlog] [subject 1 user | name]" 
rename => ;SubjectUserSid" " "[eventlog][subject 1 user sid]' ] 
rename => "System" r “[eventlog] [system] ” ] 
rename => “TargetDomainName” n “ [eventlog] [target « domain | name]" ] 
rename => "TargetLogonld" » ' [eventlog] [target . logonid]" l 
rename => "TargetUserName' , "[eventlog][target user | name]" ] 
rename => JargetUserSid" " "[eventlog] [target user sid] ] 
rename —» "ThreadID' , “thread” ] 
} 
mutate { 
remove field => [ “CurrentOrNextState” , “Description” , “EventReceivedTime” , “EventTime” , "EventTimeWr 
itten” , "IPVersion' , “KeyLength” , “Keywords” , "ImPackageName' , "LogonProcessName 
" , "LogonType' , “Name” , "Opcode' , "OpcodeValue" , "PolicyProcessingMode' , “Protocol” , 
;ProtocolType" , '"SourceModuleType' , "State" , “Task” , "TransmittedServices' , "Type 
"UserID' , "Version" 
] 
} 
} 
} 
3.6 ” Java 日 志 
之 前 在 2.2 节 有 关 codec 的 介绍 中 曾经 提 到 过 ， 对 Java 日 志 ， 除 了 使 用 multiline 做 多 行 日 志 合并 以 外 ， 还 可 以 直接 通过 Log4J 写 入 logstash 里 。 本 节 就 讲述 如 何在 Java 应 用 环境 做 到 这 点 。 
3.6.1 Log4J 配 置 
首先 ， 需 要 配置 Java 应 用 的 Log4J 设 置 ， 启 动 一 个 内 置 的 SocketAppender。 修 改 应 用 的 log4j.xm 人 配置 文件 ， 添 加 如 下 配置 段 : 
<appender name= “LOGSTASH” class= "org.apache.log4j.net.SocketAppender" > 
<param name= “RemoteHost” value= “logstash hostname” /> 
<param name= "ReconnectionDelay' value= “60000” /> 
<param name= "LocationInfo' value= "true" /» 
<param name= “Threshold” value= “DEBUG” /> 


</appender> 


然后 把 这 个 新 定义 的 appender 对 象 加 入 root logger 里 ， 可 以 跟 其 他 已 有 logger 共 存 : 


«root» 

«level value= “INFO” /> 
«appender-ref ref= "OTHERPLACE' /> 
«appender-ref ref= "LOGSTASH' /> 
«/root» 


如 果 是 log4j.properties 配 置 文件 ， 则 对 应 配置 如 下 : 


1og4j.rootLogger-DEBUG, logstash 

###SocketAppender### 
10g4j.appender.logstash-org.apache.10g4j.net.SocketAppender 
10g4j.appender.logstash.Port-4560 
10g4j.appender.logstash.RemoteHost-logstash hostname 
10g4j.appender.logstash.ReconnectionDelay-60000 
10g4j.appender.logstash.LocationInfo-true 


Log4J 会 持续 尝试 连接 你 配置 的 logstash_hostname 这 个 地 址 ， 建 立 连 接 后 ， 即 开始 发 送 


3.6.2 ”Logstash 配 置 


Dos 


志 数 据 。 


Java 应 用 端的 配置 完成 以 后 ， 开 始 设置 Logstash 的 接收 端 。 配 置 如 下 所 示 ， 其 中 4560 端 口 是 Log4j SocketAppender 的 默认 对 端 端口 : 
input { 
log4j ( 
type => *1og4j-json" 
port => 4560 


} 
} 


3.6.3 ”异常 堆栈 测试 验证 


运行 Logstash 后 ,编写 一 个 简单 的 Log4J 程 序 : 


import org.apache.1log4j.Logger; 
public class HelloExample( 
final static Logger logger - Logger.getLogger (HelloExample.class) ; 
public static void main (String[] args) ( 
HelloExample obj = new HelloExample () ; 
try{ 
obj.divide () ; 
}catch (ArithmeticException ex) { 
logger.error ( “Sorry, something wrong!” , ex) ; 
} 
private void divide () { 
int i = 10 /0; 


# javac -cp ./logstash-1.5.0.rc2/vendor/bundle/jruby/1l.9/gems/logstash-input- 
log4j-0.1.3-java/lib/log4j/log4j/1.2.17/log4j-1.2.17.jar HelloExample.java 

# java -cp .:./logstash-1.5.0.rc2/vendor/bundle/jruby/1.9/gems/logstash-input- 
10g4j-0.1.3-java/1ib/10g4j/10g4j/1.2.17/10g4j-1.2.17.jar HelloExample 


这 样 即 可 在 Logstash 的 终端 输出 看 到 如 下 事件 记录 : 


{ “message” 


divide (HelloExample.java:13) \n\tat HelloExample.main (HelloExample.java:7) " 


} 


=> "Sorry, something wrong!" , "Qversion' => “1” , “@timestamp” => “2015-07-02T13:24:45.7272” , “type” => “log4j-json” , “host” => “127.0.0.1:52420” , "path" 


=> “He 


可 以 看 到 ， 异 常 堆栈 直接 记录 在 单行 内 了 。 


3.64 JSON Event layout 


如 果 无 法 采 


Logstash 官 方 提供 了 扩展 包 ， 可 以 通过 mvnrepository.com 搜 索 下 载 : 


SocketAppender， 必 须 使 用 文件 方式 的 ， 其 实 Log4J 有 一 个 layout 特 性 ， 用 来 控制 日 志 输出 的 格式 。 和 Nginx 日 志 自 己 拼接 JSON 输 出 类 似 ， 也 可 以 通过 layout 功 能 记录 成 JSON 格 式 。 


# wget http://central.maven.org/maven2/net/logstash/1og4j/jsonevent-layout/l.7/ 
jsonevent-layout-1.7.jar 


或 者 直接 编辑 自己 项 目的 pom.xml 添 加 依赖 : 


<dependency> 
«groupId»net.logstash.1log4j«/groupId» 
«artifactlId»jsonevent-layout«/artifactld» 
«version»l.7«/version» 

</dependency> 


然后 修改 项 目的 log4j.properties 文 件 如 下 : 


1og4j 
log4j 
log4j 
1og4j 
10g4j 
log4j 


-rootCategory-WARN, RollingLog 
.appender 
.appender 
.appender 
.appender 
.appender 


.RollingLog-org.apache.10g4j.DailyRollingFileAppender 
.RollingLog.Threshold-TRACE 

.RollingLog.File-api.log 
.RollingLog.DatePattern-.yyyy-MM-dd 
.RollingLog.layout-net.logstash.log4j.JSONEventLayoutV1l 


如 果 是 log4j.xml， 则 修改 如 下 : 


<appender name- "Console" class- "org.apache.10g4j .ConsoleAppender" > 
<param name= “Threshold” value= “TRACE” 
«layout class= "net.logstash.log4j.JSONEventlayoutVl' /> 
«/appender» 


生成 的 文件 就 是 符合 Logstash 标 准 的 JSON 格 式 了 ，Logstash 使 用 下 面 配置 读 取 : 


input { 
file { 

codec => json 

path => [ "/path/to/log4j.log" ] 


生成 的 Logstash 事 件 如 下 : 


“mac” :(), 
"line number" : "29" , 


"class" : 


"org.eclipse.jetty.examples.logging.EchoFormServlet" , 


"Qversion" :1, 


"source host" : "jvstratusmbp.local" , 
"thread name" : "qtp513694835-14" , 
“message” : "Got request from 0:0:0:0:0:0:0:1$0 using Mozilla V/5.0 (Macintosh; 


"Qtimestamp' : 
"o: “INFO” , 
" : “EchoFormServlet.java” , 


“method” : “doPost” , 


Intel Mac OS X 10 9 1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/32.0. 
1700.77 SafariMV/537.36' , 


"2014-01-27719:52:35.7382" , 


"logger name" : "org.eclipse.jetty.examples.logging.EchoFormServlet" 


可 以 看 到 ， 同 样 达 到 了 效果 。 


如 果 你 使 用 的 不 是 Log4J 而 是 logback 项 目 来 记录 java 日志，Logstash 官 方 也 有 类 似 的 扩展 包 ， 在 pom.xml 中 改 成 如 下 定义 即 可 : 
«dependency» 


XgroupId»net.logstash.logback«/groupId» 
«artifactlId»logstash-logback-encoder«/artifactld» 
«version»4.4«/version» 

</dependency> 


37 MySQL 慢 查 询 日 志 


MySQL 有 多 种 


志 可 以 记录 ， 常 见 的 有 error log, slow log、general log、bin log 等 。 其 中 slow log 作 为 性 能 监控 和 优化 的 入 手 点 ， 最 为 首要 。 本 节 即 讨论 如 何 用 


general log， 格 式 处 理 基 本 类 似 ， 不 过 由 于 general 量 级 比 slow 大 得 多 ， 推 荐 采用 packetbeat 协 议 解 析 的 方式 更 高 效 地 完成 这 项 工作 。 相 关内 容 阅读 本 书 稍 后 章节 。 


MySQL slow log 的 Logstash 处 理 配 置 示例 如 下 : 


Logstash 处 理 slow log。 至 于 


input 


{ 


file { 


type 
path 


=> “mysql-slow” 
=> "/var/log/mysql/mysql-slow.log" 


codec => multiline { 


pattern => “^# User@Host:” 
negate => true 
what => “previous” 


l 
l 
} 
filter { 
# drop sleep events 


grok { 
match => { message" => “SELECT SLEEP" } 
add tag => [ “sleep drop” ] 
tag on failure => [] # prevent default _grokparsefailure tag on real records 


} 
if "sleep drop” in [tags] { 
drop {} 
} 
grok { 
match => [ “message” , ^" (? m) ^# User@Host: %{USER:user}\[[^\]]+\] @ (? : (? <clien- 
thost>\S*) ) ? N[ (? : %{IP:clientip}) ? \]\s*# Query time: $(NUMBER:query time: 
float}\s+Lock time: $(NUMBER:lock time:float]Ns*Rows sent: $(NUMBER: rows 
sent:int}\s+Rows examined: $(NUMBER:rows examined:int)Vs* (? : use $(DATA: 
database); Ns*) ? SET timestamp-$(NUMBER:timestamp); s* (? «query» (? «action»V 
w+) \st.*) \n# Time:.*$" ] 
} 


date { 
match => [ “timestamp” , “UNIX” ] 
remove field => [ “timestamp” ] 


} 
} 


配置 中 ,利用 了 grok 插 件 的 add tag 选 项 仅 在 成 功 时 添加 ， 而 tag_on_failure 选 项 仅 在 失败 时 添加 的 互 斥 特性 ， 巧 妙 地 过 滤 出 日 志 中 无 用 的 sleep 语 句 删除 掉 。 


如 下 一 段 多 行 的 MySQL slow log: 


# User@Host: logstash[logstash] @ localhost [127.0.0.1] 

# Query time: 5.310431 Lock time: 0.029219 Rows sent: 1 Rows examined: 24575727 
SET timestamp-1393963146; 

select count (*) from node join variable order by rand () ; 

# Time: 140304 19:59:14 


通过 运行 上 面 的 配置 ，Logstash 即 可 处 理 成 如 下 单个 事件 : 


{ "Gtimestamp' => '"2014-03-04719:59:06.000Z" , "message" => “# User8Host: logstash[logstash] 8 localhost [127.0.0.1]\n# Query 
time: 5.310431 Lock time: 0.029219 Rows sent: 1 Rows examined: 24575727NnSET 
timestamp-1393963146;Wnselect count (*) from node join variable order by rand () ; 
\n# Time: 140304 19:59:14" , “@version” => "1" , "tags" => [ 
[0] “multiline” 
], “type” => "mysql-slow' , “host” => "raochenlindeMacBook-Air.local'" , “path” => "/var/log/mysql/mysql-slow.log" , “user” => "logstash' , *"clienthost' => “localhost” , "cl 


后 续 即 可 针对 其 中 的 action、query time, lock time 和 rows_examined 字 段 做 监控 报警 及 Kibana 可 视 化 统计 了 。 


3.8 Docker 日 志 


Docker 是 目前 大 规模 互联 网 基础 架构 解决 方案 中 最 热门 的 技术 。 它 带 给 运 维 工程 师 一 个 截然 不 同 的 思考 角度 和 工作 方式 。 


就 日 志 层面 看 ，Docker 最 大 的 影响 在 于 : 其 最 佳 实践 要 求 一 个 容器 内 部 只 有 一 个 生命 周期 随时 可 以 消亡 的 服务 进程 。 这 也 就 意味 着 : 传统 的 写 入 磁盘 ， 固 定 采 集 方 式 的 日 志 系统 ， 无 法 正常 发 挥 作用 。 
所 以 ， 在 容器 服务 中 ， 记 录 日 志 需 要 采用 另外 的 方式 。 本 节 将 介绍 其 中 最 常见 的 两 种 : 记录 到 主机 磁盘 ， 或 通过 logspout 收 集 。 


3.8.1 ”记录 到 主机 磁盘 


默认 情况 下 ，Docker 会 将 容器 的 标准 输出 和 错误 输出 ， 保 存在 主机 的 /var/lib/docker/containers/ 目 录 下 。 所 以 ， 在 规模 比较 稳定 的 情况 下 ， 直 接 记 录 到 主机 磁盘 ， 然 后 通过 主机 上 的 Logstash 收 集 日 
也 是 不 错 的 方案 。 


at 


以 Nginx 为 例 ， 将 Nginx 访 问 日 志和 错误 日 志 输出 到 标准 输出 的 配置 如 下 : 


daemon off; 
error log /dev/stdout info; 
http T 

access log /dev/stdout; 


不 过 ， 容 器 的 特殊 性 在 这 里 又 一 次 体现 出 来 ， 容 器 中 其 实 是 没有 /dev/stdout 设 备 的 。 所 以 我 们 需要 自己 单独 处 理 一 下 ， 在 Dockerflie 里 加 上 一 句 : 


RUN 1n -sf /proc/self/fd /dev/ 


这 样 ， 既 保证 了 nginx.conf 是 主机 和 容器 通用 的 配置 ， 又 顺利 达到 目的 。 


然后 通过 如 下 Logstash 配 置 收集 即 可 : 


input { 
file { 
path => [ “/var/lib/docker/containers/*/*-json.log” ] 
codec => json 
l 
} 
filter { 
grok { 
match => [ “path” . “/ (? <container_id>\w+) -json.log' ] 
remove field => [ “path” ] 
} 
date { 
match => [ "time" , ^"ISO8601" ] 
} 


3.8.2 ”通过 logspout 收 集 


logspout 是 Docker 生 态 圈 中 最 有 名 的 日 志 收 集 方式 ， 其 设计 思路 是 : 每 个 主机 上 启动 一 个 单独 容器 运行 logspout 服 务 ， 负 责 将 同一 个 主机 上 其 他 容器 的 日 志 ， 根 据 route 设 定 ， 转 发 给 不 同 的 接收 端 。 


logspout 的 基本 用 法 如 下 : 


$ docker pull gliderlabs/logspout:latest 
$ docker run --name- "logspout" 
—-volume-/var/run/docker.sock:/tmp/docker.sock V 
gliderlabs/logspout \ 
--publish-127.0.0.1:8000:80 
syslog://remoteaddr:514 


此 外 ，logspout 提 供 动态 变更 route 的 方式 ， 如 下 所 示 : 


# curl $ (docker port `docker ps -lq` 8000) /routes \ 


-X POST N 
-d '( "source" : ( "filter name" : “* db" , “types” : “stderr” ]), “target” : 
{ “type” : “syslog” , “addr” : "remoteaddr2:5140" }}' 


这 个 配置 的 意思 是 ， 将 容器 名 带 有 db 字样 的 走 错误 输出 的 采集 的 日 志 ， 以 syslog 协 议 发 送 到 remoteaddr2 主 机 的 5140 端 口 。 


注意 ，logspout 采 用 的 是 REC5424 版 本 的 syslog 协 议 ， 所 以 如 果 使 用 的 接收 方 是 RFEC3164 版 本 的 syslog 协 议 解 析 ， 需 要 自己 调整 一 下 。 比 如 logstash-input-syslog 采 用 的 就 是 RFC3164 协 议 ， 所 以 需要 
自己 来 另外 完成 : 


input ( 


tcp { 
port => 5140 
i 
} 
filter { 
grok ( 
match => [ "message" ,  "«SYSLOG5424PRI:syslog pri» $(SYSLOG5424LINE:message]" ] 


} 


此 外 ，logspout 支 持 模 块 化 扩展 ， 所 以 ， 我 们 也 可 以 直接 在 logspout 上 处 理 成 对 Logstash 更 友好 的 格式 。 扩 展 logspout 支 持 Logstash 格 式 的 方法 如 下 : 


1) 编辑 Dockerfile， 修 改 成 如 下 内 容 : 


FROM gliderlabs/logspout:master 
ENV ROUTE URIS-logstash://host:port 


2) 编辑 modules.go， 修 改 成 如 下 内 容 : 


Package main 
import ( 
"github.com/looplab/logspout-logstash" 
— "github.com/gliderlabs/logspout/transports/udp' ) 


3) 构建 镜像 : 


docker build 


这 样 ， 后 续 Logstash 就 直接 JSON 解 析 即 可 。 


第 4 章 “性 能 与 监控 


任何 软件 都 需要 掌握 其 性 能 瓶颈 ， 以 及 线 上 运行 时 的 性 能 状态 。Logstash 也 不 例外 。 长 久 以 来 ，Logstash 在 这 方面 一 直 处 于 比较 黑 盒 的 状态 。 因 为 其 内 部 队列 使 用 的 是 标准 的 stud 库 ， 并 非 自己 实现 ， 
在 Logstash 本 身 源 代码 里 是 找 不 出 来 什么 问题 的 。 我 们 只 能 按照 其 pipeline 原 理 ， 总 结 出 来 一 些 模拟 检测 的 手段 。 本 章 主要 介绍 这 方面 的 内 容 ， 包 括 两 部 分 : 性 能 测试 与 监控 方案 。 本 章 介绍 使 用 logstash- 
input-generator 插 件 和 pv 命令 测试 Logstash 性 能 的 方案 。 并 从 Logstash 逻 辑 原理 和 JRuby 平 台 层 面 出 发 介绍 两 种 Logstash 的 监控 方式 ， 还 简要 介绍 Zabbix 上 JMX 监 控 的 配置 方式 。 


Logstash 官 方 已 经 将 性 能 监控 问题 列 入 roadmap， 或 许 在 未 来 的 1.6 或 者 2.0 版 本 中 会 有 质 的 改变 。 


4.1 性 能 测试 


logstash-input-generator 插 件 可 以 在 Logstash 内 部 生产 数据 。 实 际 运 行 的 时 候 这 个 插件 是 派 不 上 用 途 的 ， 但 这 个 插件 依然 是 非常 重要 的 插件 之 一 。 因 为 每 一 个 使 用 ELK stack 的 运 维 人 员 都 应 该 清楚 一 
个 道理 : 数据 是 支持 操作 的 唯一 真理 (否则 你 也 用 不 着 ELK) 。 所 以 在 上 线 之 前 ， 你 一 定 会 需要 在 自己 的 实际 环境 中 ， 测 试 Logstash 和 Elasticsearch 的 性 能 状况 。 这 时 ， 这 个 用 来 生成 测试 数据 的 插件 就 有 
J! 


44.1. 配置 示例 
配置 示例 代码 如 下 : 


input { 
generator { 
count => 10000000 
message => '{ "keyl' : "valuel' , "key2" :[1,2], “key3” :{ “subkeyl” : “subvaluel” }}' 
codec => json 


} 


插件 的 默认 生成 数据 ，message 内 容 是 “Hello World”， 你 可 以 根据 自己 的 实际 需要 这 里 来 写 其 他 内 容 。 


41.2 ”使 用 方式 


做 测试 有 两 种 主要 方式 ， 下 面 分 别 介绍 。 


1. 配 合 LogStash: : Outputs: : Null 


logstash-nput-generator 是 无 中 生 有 ，logstash-output-null 则 是 锯 嘴 葫芦 。 事 件 流转 到 这 里 直接 就 略 过 ， 什 么 操作 都 不 做 。 相 当 于 只 测试 Logstash 的 pipe 和 filter 效 率 。 测 试 过 程 非常 简单 : 


# time ./bin/logstash -f generator null.conf 
real 3m0.864s T 

user 3m39.031s 

sys 0m51.621s 


2. 使 用 pv 命令 配合 LogStash::Outputs::Stdout 和 LogStash::Codecs::Dots 


上 面 的 这 种 方式 虽然 想法 挺 好 ， 不 过 有 个 小 漏洞 : Logstash 是 在 JVM 上 运行 的 ， 有 一 个 明显 的 启动 时 间 ， 运 行 也 有 一 段 时 间 的 预 热 后 才 算 稳 定 运行 。 所 以 ， 要 想 更 真实 地 反应 Logstash 在 长 期 运行 时 候 
的 效率 ， 还 有 另 一 种 方法 : 


output { 
stdout ( 
codec => dots 
} 


LogStash: : Codecs: : Dots 也 是 一 个 另类 的 Codec 插 件 ， 其 作用 是 : 把 每 个 event 都 变 成 一 个 点 (.) ， 这 样 ， 在 输出 的 时 候 ， 就 变 成 了 一 个 一 个 的 .在 屏幕 上 。 显 然 这 也 是 一 个 为 了 测试 而 存在 的 插 
件 。 


下 面 就 要 介绍 pv 命令 了 。 这 个 命令 的 作用 就 是 作 实时 的 标准 输入 、 标 准 输出 监控 。 我 们 这 里 就 用 它 来 监控 标准 输出 : 


# ./bin/logstash -f generator dots.conf | pv -abt > /dev/null 
2.2MiB 0:03:00 [12.5kiB/s] 


可 以 很 明显 地 看 到 在 前 几 秒 中 ， 速 度 是 0B/s， 因 为 JVM 还 没 启动 起 来 呢 。 开 始 运行 的 时 候 ， 速 度 依然 不 快 。 慢 慢 增长 到 比较 稳定 的 状态 ， 这 时 候 的 才 是 你 需要 的 数据 。 


这 里 单位 是 B/s， 但 是 因为 一 个 event 就 输出 一 个 ， 也 就 是 1B。 所 以 12.5kiB/s 就 相当 于 是 12.5k event/s (kiB 指 KB) 。 


Qua 


如 果 你 在 CentOS 上 通过 yum 安 装 的 pv 命令 ， 版 本 较 低 ， 可 能 还 不 支持 -a 参 数 ， 单 纯 靠 -bt 参数 看 起 来 还 是 有 点 累 的 。 


4.1.3 ”额外 的 话 


既然 单独 花 这 么 一 节 来 说 测试 ， 这 里 想 额 外 谈 谈 一 个 很 常见 的 话题 :ELK 的 性 能 怎么 样 ? 


其 实 这 压根 就 是 一 个 不 正确 的 提问 。ELK 并 不 是 一 个 软件 ， 而 是 一 个 并 不 耦合 的 套件 。 所 以 ， 我 们 需要 分 拆 开 讨论 这 三 个 软件 的 性 能 如 何 ? 怎么 优化 ? 


“ Logstash 的 性 能 。 这 是 最 让 新 人 迷 敬 的 地 方 。 因 为 Logstash 本 身 并 不 维护 队列 ， 所 以 整个 日 志 流 转 中 任意 环节 的 问题 都 可 能 看 起 来 像 是 Logstash 的 问题 。 这 里 ， 需 要 熟练 使 用 本 节 说 的 测试 方法 ， 针 对 自 
己 的 每 一 段 配 置 ， 都 确定 其 性 能 。 另 一 方面 ， 就 是 本 书 之 前 提 到 过 的 ，Logstash 给 自己 的 线程 都 设置 了 单独 的 线程 名 称 ， 你 可 以 在 top-H 结 果 中 查看 具体 线程 的 负载 情况 。 

` Flasticsearch 的 性 能 。 这 里 最 需要 强调 的 是 : Elasticseatch 是 一 个 分 布 式 系统 ， 从 来 没有 分 布 式 系统 要 跟 人 比较 单机 处 理 能 力 的 说 法 。 所 以 ， 更 需要 关注 的 是 : 在 确定 的 单机 处 理 能 力 的 前 提 下 ， 性 能 是 
否 能 做 到 线性 扩展 。 当 然 ， 这 不 意味 着 说 提高 处 理 能 力 只 能 靠 加 机 器 了 一 一 有 效 利 用 mapping API 是 非常 重要 的 。 不 过 暂时 就 不 在 这 里 讲述 了 。 

: Kipana 的 性 能 。 通 常 来 说 ，Kibana 只 是 一 个 单 页 Web 应 用 ， 只 需要 Nginx 发 布 静态 文件 即 可 ， 没 什么 性 能 问题 。 页 面 加 载 缓慢 ， 基 本 上 是 因为 Elasticsearch 的 请 求 响应 时 间 本 身 不 够 快 导致 的 。 不 过 一 定 
要 细 究 的 话 ， 也 能 找 出 点 Kibana 本 身 性 能 相关 的 话题 :因为 Kibana 3 默认 是 连接 固定 的 一 个 Blasticsearch 节 点 的 IP 端 口 的 ， 所 以 这 里 会 涉及 一 个 浏览 器 的 同一 IP 并 发 连接 数 的 限制 。 其 次 ， 就 是 Kibana 用 的 
AngularjS 使 用 了 Promise.then 的 方式 来 处 理 HTTP 请 求 响应 。 这 是 异步 的 。 


42 ”监控 方案 


Logstash 作 为 日 志 收集 工具 ， 其 最 重要 的 监控 点 就 是 日 志 传输 的 状态 。 在 1.5 版 本 之 前 ， 大 家 通常 采用 上 节 中 logstash-input-generator 插 件 生成 的 数据 来 作为 运行 时 的 监控 日 志 ， 但 是 日 志 内 容 和 生成 
方式 ， 对 外 部 监控 系统 并 不 是 非常 方便 。Logstash 官 方 为 此 单独 开发 了 heartbeat 插 件 用 来 实现 更 友好 的 状态 监控 。 此 外 ， 我 们 也 可 以 通过 JVM 平 台 上 通用 的 JMX 接 口 ， 详 细 监 控 其 JVM Heap、 
threadcount 等 细节 信息 。 本 节 会 以 Zabbix 监 控 系 统 为 例 ， 介 绍 如 何 使 用 Zabbix 监 控 Logstash 进 程 细 节 。 


4.2.1 logstash-input-heartbeat 心 跳 检测 方式 


缺少 内 部 队列 状态 的 监控 办 法 一 直 是 Logstash 最 为 人 诉 病 的 一 点 。 从 logstash-1.5.1 版 开始 ， 新 发 布 了 一 个 logstash-input-heartbeat 插 件 ， 实 现 了 一 个 最 基本 的 队列 堵塞 状态 监控 。 
配置 示例 如 下 : 
input { 


heartbeat ( 
message => “epoch” 
interval => 60 
type => “heartbeat” 
add field => { 
^ "zbxkey' => “logstash.heartbeat” , 
"zbxhost' => "logstash hostname" 
} 
} 
tcp { 
port => 5160 
l 


output ( 
if [type] == “heartbeat” ( 
file ( 
path => "/datal/logstash-log/local6-5160-$ (*YYYY.MM.dd).log" 
} 
zabbix { 
zabbix host => "zbxhost" 


zabbix key => "zbxkey 
zabbix server host => "zabbix.example.com" 
zabbix value => "clock" 
} 
) else { 
elasticsearch { } 


} 


示例 中 ， 同 时 将 数据 输出 到 本 地 文件 和 zabbix server。 注 意 ，logstash-output-zabbix 并 不 是 标准 插件 ， 需 要 额外 安装 : 


bin/plugin install logstash-output-zabbix 


文件 中 记录 的 就 是 heartbeat 事 件 的 内 容 ， 示 例如 下 : 


{ "clock" :1435191129, "host" : "logtes004.mweibo.bx.sinanode.com' , “@version” : "1" , “@ 
timestamp” : "2015-06-25T00:12:09.0422" , "type" : “heartbeat” , "zbxkey' : "logstash. 
heartbeat” , "zbxhost' : "logstash hostname" } 


可 以 通过 文件 最 后 的 clock 和 @timestamp 内 容 ， 对 比 当前 时 间 ， 来 判断 Logstash 内 部 队列 是 否 有 堵塞 。 


4.2.2 ”JMX 启 动 参数 方式 


Logstash 是 一 个 运行 在 JVM 上 的 软件 ， 也 就 意味 着 JMX 这 种 对 JVM 的 通用 监控 方式 对 Logstash 也 是 一 样 有 效果 的 。 要 给 Logstash 启 用 JMX， 需 要 修改 ./bin/logstash.lib.sh 中 $JAVA_OPTS 变 量 的 定 
义 ， 或 者 在 运行 时 设置 LS JAVA_OPTS 环 境 变量 。 


在 ./bin/logstash.lib.sh 第 34 行 JAVA_OPTS= “$JAVA_OPTS-Djava.awt.headless=true” 下 ， 添 加 如 下 几 行 : 


JAVA OPTS- "SJAVA OPTS -Dcom.sun.management.jmxremote 
JAVA OPTS- "SJAVA OPTS -Dcom.sun.management.jmxremote.port-9010" 

JAVA OPTS- "SJAVA OPTS -Dcom.sun.management.jmxremote.local.only-false" 
JAVA OPTS- "SJAVA OPTS -Dcom.sun.management.jmxremote.authenticate-false" 
JAVA OPTS- “$JAVA OPTS -Dcom.sun.management.jmxremote.ssl-false" 


重启 Logstash 服 务 ，JMX 配 置 即 可 生效 。 


有 JMX 以 后 ， 我 们 可 以 通过 Jconsole 界 面 查 看 ， 也 可 以 通过 Zabbix 等 监控 系统 做 长 期 监控 。 甚 至 Logstash 自 己 也 有 插件 logstash-input-jmx 来 读 取 远 程 JMX 数 据 。 下 面 介绍 Zabbix 监 控 方案 。 


Zabbix 监 : 


Zabbix 里 提供 了 专门 针对 JMX 的 监控 项 。 详 见 : https://www.zabbix.com/documentation/2.2/manual/config/items/itemtypes/jmx_monitoring 


注意 ，zabbix-server 本 身 并 不 直接 对 JMX 发 起 请 求 ， 而 是 单独 有 一 个 JavaGateway 作 为 中 间 代 理 层 角色 。zabbix-server 的 java poller 连 接 zabbix-java-gateway， 由 zabbix-java-gateway 去 获取 远程 
JMX 信 息 。 所 以 ， 在 zabbix-web 配 置 之 前 ， 需 要 先 配 置 Zabbix Server 相 关 进 程 和 设置 : 


# yum install zabbix-java-gateway 

# cat >> /etc/zabbix/zabbix-server.conf ««EOF 
JavaGateway-127.0.0.1 

JavaGatewayPort-10052 

StartJavaPollers-5 

EOF 

# /etc/init.d/zabbix-java-gateway restart 

# /etc/init.d/zabbix-server restart 


然后 在 zabbix-web 上 Configuration 页 ， 给 运行 Logstash 的 主机 的 Host 配 置 添加 JMX 接 口 ，Port 即 为 上 面 定义 的 9010 端 口 。 


最 后 添加 ltem，Type 下 拉 框 选择 JMX agent，Key 文 本 框 输入 jmx["java.lang: type=Memory", 


"HeapMemoryUsage.used"]， 保 存 即 可 。 


JMX 有 很 多 Key 可 以 监控 , 具体 的 值 ， 可 以 通过 Jconsole 参 看 。 如 图 4-1 所 示 ， 如 果 要 监控 线程 数 ， 就 可 以 写成 mx["java.lang: type=Threading", "ThreadCount"], 


Java AN OE MHA 


javax.management openmbean.SimpleType(name « java.! 
int 


ThreadAllocatedMemoryt nabled 
ThreadAllocated MemorySupporcoed 


图 4-1 jconsole 


有 了 监控 项 和 数据 ， 后 续 的 Graph、Screen、Trigger 定 义 ， 这 里 就 不 再 讲述 了 ， 有 需要 的 读者 可 以 自行 查找 Zabbix 相 关 资 料 。 


第 5 章 扩展 方案 


之 前 章节 讲述 的 都 是 单个 Logstash 进 程 ， 及 其 对 数据 的 读 取 、 解 析 和 输出 处 理 。 但 是 在 生产 环境 中 ， 从 每 台 应 用 服务 器 运行 Logstash 进 程 并 将 数据 直接 发 送 到 Elasticsearch 里 ， 显 然 不 是 第 一 选择 ， 原 
因 有 三 : 第 一 ， 过 多 的 客户 端 连 接 对 Elasticsearch 是 一 种 额外 的 压力 ; 第 二 ， 网 络 抖动 会 影响 到 Logstash 进 程 ， 进 而 影响 生产 应 用 ; 第 三 ， 运 维 人 员 未 必 愿 意 在 生产 服务 器 上 部 署 Java， 或 者 让 Logstash 跟 
业务 代码 争夺 java 资源。 所 以 ， 在 实际 运用 中 ，Logstash 进 程 会 被 分 为 两 个 不 同 的 角色 。 运 行 在 应 用 服务 器 上 的 尽量 减轻 运行 压力 ， 只 做 读 取 和 转发 ， 这 个 角色 叫做 Shipper; 运行 在 独立 服务 器 上 的 完成 
数据 解析 处 理 ， 负 责 写 入 Elasticsearch 的 角色 ， 叫 Indexer。 


Logstash 作 为 无 状态 的 软件 ， 配 合 消息 队列 系统 ， 可 以 很 轻松 地 做 到 线性 扩展 。 本 章 首先 会 介绍 最 常见 的 两 个 消息 队列 与 Logstash 的 配合 : Redis 和 kafka。 


此 外 ，Logstash 作 为 一 个 框架 式 的 项 目 ， 并 不 排斥 ， 甚 至 欢迎 与 其 他 类 似 软件 进行 混搭 式 的 运行 。 本 章 随 后 介绍 一 些 其 他 日 志 处 理 框架 以 及 如 何 与 Logstash 共 存 的 方式 。 希 望 大 家 各 取 所 长 ， 做 好 最 适 
合 自己 的 日 志 处 理 系统 ， 这 些 框架 包括 : logstash-forwarder，Logstash 官 方 自己 推出 的 轻 量 级 shipper 方 案 。Rsyslog，RHEL6 默 认 自 带 的 软件 ， 本 章 介绍 最 新 的 Rsyslog v8 版 的 全 新 语法 和 扩展 插件 体 
系 。Nxlog，Windows 平 台 上 最 推荐 的 日 志 收集 软件 。Heka，Meozilla 公 司 模仿 Logstash 重 写 的 产品 ， 对 Golang 有 偏好 的 读者 不 妨 一 试 。Fluentd， 日 本 最 流行 的 日 志 处 理 系统 ，CRuby 语 言 + 事 件 驱动 
库 ， 并 提供 有 针对 各 编程 语言 的 模块 。Message: : Passing，Perl5 社 区 模仿 Logstash 写 的 项 目 ， 基 于 libev 事 件 驱 动 库 ， 同 时 ，Perl5 的 正则 性 能 比 Logstash 也 要 高 4 倍 以 上 。 


5.1 通过 Redis 队 列 扩展 


Redis 服 务 器 是 Logstash 官 方 推荐 的 Broker 选 择 。Broker 角 色 也 就 意味 着 会 同时 存在 输入 和 输出 两 个 插件 。 本 书 会 拆 解 Logstash 中 和 Redis 有 关 的 这 两 个 插件 ， 力 图 让 读者 了 解 这 种 扩展 方式 的 实质 ， 做 
到 灵活 的 部 署 和 使 用 。 


5.1.1 ” 读 取 Redis 数 据 


LogStash: : Inputs: : Redis 支 持 三 种 data_type (实际 上 是 redis type) ， 不 同 的 数据 类 型 会 导致 实际 采用 不 同 的 Redis 命 令 操作 : 


' list =>BLPOP 
* channel Z2 SUBSCRIBE 
* pattern. channel -2 PSUBSCRIBE 


注意 到 了 么 ?这 里 面 没 有 GET 命 令 ! 


Redis 服 务 器 通常 都 是 用 作 NoSQL 数 据 库 ， 不 过 Logstash 只 是 


1. 配 置 示例 


input { 
redis ( 
data type => "pattern channel" 
key => "logstash-*" 
host => "192.168.0.2" 
port => 6379 
threads => 5 


来 做 消息 队列 。 所 以 不 要 担心 Logstash 里 的 Redis 会 撑 爆 你 的 内 存 和 磁盘 。 


2. 命 令 行 验证 


首先 确认 你 设置 的 host 服 务 器 上 已 经 运行 了 redis-server 服 务 ， 然 后 打开 终端 运行 Logstash 进 程 等 待 输入 数据 ， 然 后 打开 另 一 个 终端 ， 输 入 redis-cli 命 令 ( 先 安装 好 redis 软 件 包 ) ， 在 交互 式 提示 符 后 


面 输入 PUBLISH logstash-demochan "hello world" : 


# redis-cli 


127.0.0.1:6379» PUBLISH logstash-demochan "hello world" 


你 会 在 第 一 个 终端 里 看 到 Logstash 进 程 输出 类 似 下 i 


{ “message” => “hello world” , “@version” => “1” , “@timestamp” => “2014-08-08T16:26:29.3992” 


Oze 
这 个 事件 里 没有 host 字 段 ! (或 许 这 算是 bug……) 
3. 直 接 输 入 JSON 数 据 


如 果 你 想 通 过 Redis 的 频道 给 Logstash 事 件 添加 更 多 字段 ， 直 接 向 频道 发 布 JSON 字 符 捉 就 可 以 了 。LogStash: 


继续 在 第 二 个 终端 的 交互 式 提示 符 下 输入 如 下 内 容 : 


: Inputs: 


: Redis 会 直接 把 JSON 转 换 成 事件 。 


127.0.0.1:6379» PUBLISH logstash-chan '{ “message” : "hello world" , "8 
version" : “1” , "Qtimestamp' : "2014-08-08T16:34:21.8652" , “host” : 
cBook-Air.local' , "keyl' : "valuel" }' 


"raochenlindeMa 


你 会 看 到 第 一 个 终端 里 的 Logstash 进 程 随即 也 返回 新 的 内 容 ， 如 下 所 示 : 


{ “message” => “hello world” , “@version” => “1” , “@timestamp” 


} 


=> “2014-08-09T00:34:21.865+08:00” , “host” 


=> “raochenlindeMacBook-Air.local” , "keyl' => “valuel” 


看 ， 新 的 字段 出 现 了 ! 现在 ， 你 可 以 要 求 开发 工程 师 直接 向 你 的 Redis 频 道 发 送信 息 好 了 ， 一 切 自 动 搞定 。 


4 输入 建议 


这 里 我 们 建议 的 是 使 
pattern_channel 类 型 就 可 以 帮助 你 一 次 订阅 全 部 Logstash 相 关 频 道 ! 


5.1.2 ”采用 list 类 型 扩展 Logstash 


如 上 小 节 提 到 的 ， 之 前 两 个 使 用 场景 采用 了 同样 的 配 
订阅 了 该 频道 的 Logstash 进 程 同时 接收 到 ， 然 后 输出 重复 内 容 ! 


Oez 


你 可 以 尝试 再 做 一 次 上 面 的 实验 ， 这 次 在 两 个 终端 同时 启动 logstash-ftedis-input.conf 进 程 ， 结 果 会 是 两 个 终端 都 输出 消息 。 


pattern_channel 作 为 输入 插件 的 data_type 设 置 值 。 因 为 实际 使 用 中 ， 你 的 Redis 频 道 可 能 有 很 多 不 同 的 keys， 一 般 命名 成 logstash-chan-%{type} 这 样 的 形式 。 这 时 候 


， 即 数据 类 型 为 频道 发 布 订阅 方式 。 这 种 方式 在 需要 扩展 Logstash 成 多 节点 集群 的 时 候 ， 会 出 现 一 个 问题 : 通过 频道 发 布 的 一 条 信息 ， 会 被 所 有 


这 种 时 候 ， 就 需要 用 list 类 型 。 在 这 种 类 型 下 ， 数 据 输入 到 Redis 服 务 器 上 和 暂 存 ，Logstash 则 连 上 Redis 服 务 器 取 走 (BLPOP 命 令 ， 所 以 只 要 Logstash 不 堵塞 ，Redis 服 务 器 上 也 不 会 有 数据 堆积 占用 空 
间 ) 数据 。 
1 .配置 示例 
input ( 
redis ( 
batch count => 1 
data type => "list" 
key => "logstash-list" 
host => "192.168.0.2" 
port => 6379 
threads => 5 
} 
} 
2. 命 令 行 验证 


这 次 我 们 同时 在 两 个 终端 运行 logstash-f redis-input-list.conf 进 程 。 然 后 在 第 三 个 终端 里 启动 redis-cli 命 令 交 互 : 


$ redis-cli 


127.0.0.1:6379» RPUSH logstash-list "hello world" (integer) 1 


这 时 候 你 可 以 看 到 ， 只 有 一 个 终端 输出 了 结果 。 


连续 RPUSH 几 次 ， 可 以 看 到 两 个 终端 近 平 各 自 输出 一 半 条 目 。 


3. 批 量 推送 


RPUSH 支 持 batch 方 式 ， 修 改 Logstash 配 置 中 的 batch_count 值 ， 作 为 示例 这 里 只 改 到 2， 实 际 运用 中 可 以 更 大 (事实 上 LogStash: : Outputs: : Redis 对 应 这 点 的 batch_event 配 置 默认 值 就 是 


50) 。 


由 | 


看 启 Logstash 进 程 后 ，redis-cli 命 令 中 改 成 如 下 发 送 : 


127.0.0.1:6379» RPUSH logstash-list “hello world” “hello world” “hello 
world” “hello world” “hello world” “hello world” (integer) 3 


可 以 看 到 ， 两 个 终端 也 各 自 输 出 一 部 分 结果 。 而 你 只 用 了 一 次 RPUSH 命 令 。 


5.1.3. ”输出 到 Redis 


1. 配 置 示例 


input ( stdin {} ) 
output { 
redis ( 
data type => "channel" 
key => "logstash-chan-$ (*yyyy.MM.dd)" 
} 


2. 命 令 行 验证 


我 们 还 是 继续 先 用 redis-cli 命 令 行 来 演示 logstash-output-redis 插 件 的 实质 。 


运行 Logstash 进 程 ， 然 后 另 一 个 终端 启动 redis-cli 命 令 。 输 入 订阅 指定 频道 的 Red 


is 命令 ( "SUBSCRIBE logstash-chan-2014.08.08" ) 后 ， 首 先 会 看 到 一 个 订阅 成 功 的 返回 信息 。 如 下 所 示 : 


# redis-cli 

127.0.0.1:6379» SUBSCRIBE logstash-chan-2014.08.08 
Reading messages: (press Ctrl-C to quit) 

1) "subscribe" 

2)  "logstash-chan-2014.08.08" 

3) (integer) 1 


好 ， 在 运行 Logstash 的 终端 里 输入 “hello world” 字 符 串 。 切 换 回 redis-cli 的 终端 ， 你 发 现 已 经 自动 输出 了 一 条 信息 : 


1) “message” 
2)  "logstash-chan-2014.08.08" 


3) “{\” messageN “:\” hello worldN ",V' @version\ “:\” 1\ NA GtimestampV ":N" 2014-08- 


08716:34:21.8652N “,\” host\ “:\” raochenlindeMacBook-Air.localN *) 


3.Logstash 架 构 中 的 broker 


上 面 那 条 信息 看 起 来 是 不 是 非常 眼熟 ”这 一 串 字符 其 实 就 是 我 们 在 前 面 5.1.1 节 “ 读 取 Redis 数 据 ” 中 使 用 的 那 段 数据 。 


看 ， 这 样 就 把 logstash-output-redis 和 logstash-input-redis 串 联 起 来 了 吧 ! 


实 上 ， 这 就 是 我 们 使 用 Redis 服 务 器 作为 Logstash 架 构 中 Broker 角 色 的 原理 。 


TIT 


让 我 们 把 这 两 节 中 不 同 配置 的 Logstash 进 程 分 别 在 两 个 终端 运行 起 来 ， 这 次 不 再 要 运行 redis-cli 命 令 了 。 在 配 有 logstash-output-redis 这 端 输入 “hello world" ， 配 有 logstash-input-redis 的 终端 


上 ， 就 自动 输出 数据 了 ! 


4 告警 用 途 


我 们 还 可 以 用 其 他 程序 来 订阅 redis 频 道 ， 程 序 里 就 可 以 随意 写 其 他 逻辑 了 。 你 可 以 看 看 logstash-output-juggernaut 插 件 的 原理 。 这 个 Juggernaut 就 是 基于 redis 服 务 器 和 socket.io 框 架构 建 的 。 利 


它 Llogstash 可 以 直接 向 webkit 等 支持 socket.io 的 浏览 器 推送 告警 信息 。 


5.2 ”通过 Kafka 队 列 扩展 


Kafka 是 一 个 高 吞吐 量 的 分 布 式 发 布 订阅 日 志 服务 。 目 前 已 经 在 各 大 公司 中 广泛 使 


。 和 之 前 采用 Redis 做 轻 量 级 消息 队列 不 同 ，Kafka 利 用 磁盘 作 队列 ， 所 以 也 就 无 所 谓 消 息 缓冲 时 的 磁盘 问题 。 此 


外 ， 如 果 公 司 内 部 已 有 Kafka 服 务 在 运行 ，Logstash 也 可 以 快速 接 入 ， 免 去 重复 建设 的 麻烦 。 


如 果 打算 新 建 Kafka 系 统 的 ， 请 参考 Kafka 官 方 入 门 文档 : http://kafka.apache.o 


5.2.1 Logstash1.4 版 本 插件 的 安装 


rg/documentation.html#quickstart 


Logstash 从 1.5 版 本 开始 才 集 成 了 Kafka 支 持 。 如 果 你 使 用 的 还 是 1.4 版 本 ， 需 要 


己 单独 安装 logstash-kafka 插 件 。 揪 件 地 址 见 : https://github.com/joekiller/logstash-kafka。 


插件 本 身 内 容 非 常 简单 ， 其 主要 依赖 同一 作者 写 的 jruby-kafka (https://github.com/joekiller/jruby-kafka) 模块 。 需 要 注意 的 是 : 该 模块 仅 支 持 Kafka-0.8 版 本 。 如 果 是 使 用 0.7 版 本 kafka 的 ， 将 无 


法 直接 使 jruby-kafka 该 模块 和 logstash-kafka 插 件 。 


安装 按照 官方 文档 完全 自动 化 的 安装 。 或 是 可 以 通过 以 下 方式 手动 自己 安装 插件 ， 


1) 下 载 Logstash 并 解压 重 命名 为 ./logstash-1.4.0 文 件 目录 。 


2) 下 载 kafka 相 关 组 件 ， 以 下 示例 选 的 为 kafka_2.8.0-0.8.1.1-src (https://www 


不 过 重点 注意 的 是 Kafka 的 版 本 ， 上 面 已 经 指出 了 。 


.apache.org/dyn/closer.cgipath=/kafka/0.8.1.1/kafka-0.8.1.1-src.tgz) ， 并 解压 重 命名 为 ./kafka_2.8.0-0.8.1.1。 


3) 从 releases (https:;//github.com/joekiller/logstash-kafka/releases) 页 下 载 logstash-kafka v0.4.2 版 ， 并 解压 重 命名 为 ./logstash-kafka-0.4.2。 


4) 从 ./kafka_2.8.0-0.8.1.1/libs 目 录 下 复制 所 有 的 jar 文 件 拷贝 到 ./logstash-1.4.0/vendor/jar/kafka_2.8.0-0.8.1.1/libs 下 ， 其 中 你 需要 创建 kafka_2.8.0-0.8.1.1/libs 相 关 文 件 夹 及 目录 。 


5) 分 别 复制 ./logstash-kafka-0.4.2/logstash 里 的 inputs 和 outputs 下 的 kafka.rb， 拷 贝 到 对 应 的 ./logstash-1.4.0/lib/logstash 里 的 inputs 和 outputs 对 应 目录 下 。 


6) 切换 到 ./logstash-1.4.0 目 录 下 ， 现 在 需要 运行 logstash-kafka 的 gembag.rb 脚 本 去 安装 jruby-kafka 库 ， 执 行 以 下 命令 : GEM HOME-vendor/bundle/jruby/1.9 GEM_PATH=java-jar 
vendor/jar/jruby-complete-1.7.11.jar--1.9http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/15426/OEBPS/Text/../logstash-kafka- 


0.4.2/gembag.rbhttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/15426/OEBPS/Text/../logstash-kafka-0.4.2/logstash-kafka.gemspec, 


7) 现在 可 以 使 用 logstash-kafka 插 件 运行 Logstash 了 。 


5.2.2 Input 配置 


以 下 配置 可 以 实现 对 kafka 读 取 端 (又 叫 消费 者 ，consumer) 的 基本 使 用 。 读 取 端 更 多 详细 的 配置 请 查看 http://kafka.apache.org/documentation.html#consumerconfigs kafka 官 方 文档 的 消费 者 
部 分 配置 文档 。 


input ( 
kafka ( 
Zk connect => "localhost:2181" 
group id => "logstash" 
topic id => "test" 


reset beginning => false # boolean (optional) , default: false 
consumer threads => 5 # number (optional) , default: 1 
decorate events => true # boolean (optional) , default: false 


读 取 端 的 一 些 比较 有 用 的 配置 项 : 


“ group_id: 消费 者 分 组 ， 可 以 通过 组 ID 去 指定 ， 不 同 的 组 之 间 消 费 是 相互 不 受 影响 的 ， 相 互 隔离 。 

topic id: 指定 消费 话题 ， 也 是 必 填 项 目 ， 指 定 消 费 某 个 ropic， 这 个 其 实 就 是 订阅 某 个 主题 ， 然 后 去 消费 。 

“ reset_beginning: Logstash 启 动 后 从 什么 位 置 开始 读 取 数 据 ， 上 默认 是 结束 位 置 ， 也 就 是 说 Logstash 进 程 会 以 从 上 次 读 取 结束 时 的 偏 移 量 开始 继续 读 取 ， 如 果 之 前 没有 消费 过 ， 那 么 就 开始 从 头 读 取 . 如 果 你 
是 要 导入 原 有 数据 ， 把 这 个 设 定 政 成 “true”，Logstash 进 程 就 从 头 开始 读 取 .有 点 类 似 cat， 但 是 读 到 最 后 一 行 不 会 终止 ， 而 是 变 成 tail-F， 继 续 监 听 相 应 数据 。 

decorate_events: 在 输出 消息 的 时 候 会 输出 自身 的 信息 包括 : 消费 消息 的 大 小 ，topic 来 源 以 及 consumer 的 group 信 息 。 
: rebalance max retries: 当 有 新 的 consumer (Logstash) 加 入 到 同一 group 时 ， 将 会 feblance ， 此 后 将 会 有 pattitions 的 消费 端 迁移 到 新 的 consumer 上 ， 如 果 一 个 consumer 获 得 了 某 个 pattition 的 消费 权限 ,那么 


它 将 会 向 zookeeper 注 册 ，Partition Owner tegistty 节 点 信息 ， 但 是 有 可 能 此 时 旧 的 consumet 尚 没有 释放 此 节点 ， 此 值 用 于 控制 ， 注 册 节 点 的 重 试 次 数 。 


:consumet_ timeout ms: 指定 时 间 内 没有 消息 到 达 就 抛 出 异常 ， 一 般 不 需要 改 。 


以 上 是 相对 重要 参数 的 使 用 示例 ， 更 多 参数 可 以 选项 可 以 跟 据 https://github.com/joekiller/logstash-kafka/blob/master/README.md 查 看 input 默 认 参 数 。 


Oza 

想 要 使 用 多 个 Logstash 进 程 协同 消费 同一 个 topic 的 话 ， 那 么 需要 把 两 个 或 多 个 Logstash 进 程 配置 成 相同 的 group_id 和 topic id， 但 是 前 提 是 要 把 相应 的 topic 分 多 个 pattitions (IX). ， 多 个 消费 者 消费 是 无 法 保 
证 消息 的 消费 顺序 性 的 。 

这 里 解释 下 ， 为 什么 要 分 多 个 partitions，kafka 的 消息 模型 是 对 topic 分 区 以 达到 分 布 式 效果 。 每 个 topic 下 的 不 同 的 partitions 只 能 有 一 个 Owner 去 消费 。 所 以 只 有 多 个 分 区 后 才能 启动 多 个 消费 者 ， 对 应 不 同 
的 区 去 消费 。 其 中 协调 消费 部 分 是 由 setver 端 协调 而 成 。 不 必 使 用 者 考虑 太 多 。 只 是 消息 的 消费 则 是 无 序 的 。 


总 之 ， 保 证 消息 的 顺序 ， 那 就 只 用 一 个 pattition。kafka 的 每 个 pattition 只 能 同时 被 同一 个 group 中 的 一 个 consumer 消 费 。 


5.2.3 Output 配置 


以 下 配置 可 以 实现 对 kafka 写 入 端 (又 叫 生产 者 ，producer) 的 基本 使 用 。 写 入 端 更 多 详细 的 配置 请 查看 http://kafka.apache.org/documentation.html#producerconfigs kafka 官 方 文档 的 生产 者 
部 分 配置 文档 。 


output ( 
kafka ( 
broker list => "localhost:9092" 
topic id => "test" 
compression codec => “snappy” # string (optional) , one of [ “none”, “gzip, “snappy” l, 
default: "none" 


写 入 端的 一 些 有 用 配置 如 下 所 示 。 


* compression codec: 消息 的 压缩 模式 ， 黑 认 是 none， 可 以 有 gzip 和 snappy (暂时 还 未 测试 开启 压缩 与 不 开启 的 性 能 ， 数 据 传输 大 小 等 对 比 ) 。 


“ compressed_topics: 可 以 针对 特定 的 topic 进 行 压缩 ， 设 置 这 个 参数 为 topic， 表 示 此 topic 进 行 压缩 。 

: request, required acks: 消息 的 确认 模式 。 可 以 设置 为 以 下 几 种 : 
“ 设置 为 0; 生产 者 不 等 待 broker 的 回应 ， 只 管 发 送 .会 有 最 低能 的 延迟 和 最 差 的 保证 性 (在 服务 器 失败 后 会 导致 信息 丢失 ) 
“ 设置 为 1: 生产 者 会 收 到 leader 的 回应 在 leader 写 入 之 后 .( 在 当前 leader 服 务 器 为 复制 前 失败 可 能 会 导致 信息 丢失 ) 
“ 设置 为 -1: 生产 者 会 收 到 leadetr 的 回应 在 全 部 拷贝 完成 之 后 。 

: partitioner class: 分 区 的 策略 ， 默 认 是 hash 取 模 。 


* send. buffer bytes: socket 的 缓存 大 小 设置 ， 其 实 就 是 缓冲 区 的 大 小 。 


此 外 ， 还 有 一 系列 和 消息 模式 相关 的 配置 : 
t setializef class: 消息 体 的 系列 化 处 理 类 ， 转 化 为 字 节 流 进行 传输 ， 请 注意 必须 和 下 面 的 Key_setializer class 使 用 相同 的 类 型 。 
* key setializer class: 默认 的 是 与 serializer_class 相 同 。 
“ producer, type: 生产 者 的 消息 发 送 模式 。async 异 步 发 送 ，sync 同 步 发 送 。 
.queue_buffering max ms: 异步 模式 下 ， 会 在 设置 的 时 间 缓存 消息 ， 并 一 次 性 发 送 。 
' queue, buffering max messages: 异步 的 模式 下 ， 最 长 等 待 的 消息 数 。 
* queue, enqueue, timeout ms: 异步 模式 下 ， 进 入 队列 的 等 待 时 间 ， 若 是 设置 为 0， 那 么 要 么 进入 队列 ， 要 么 直接 抛弃 。 


* batch. num messages: 异步 模式 下 ， 每 次 发 送 的 最 大 消息 数 ， 前 提 是 触发 了 queue_buffering_max_messages 或 是 queue_enqueue_timeout_ms 的 限制 。 


以 上 是 相对 重要 参数 的 使 用 示例 ， 更 多 参数 可 以 选项 可 以 跟 据 https://github.com/joekiller/logstash-kafka/blob/master/README.md 查 看 output 默 认 参 数 。 


codec 的 运用 


默认 情况 下 ， 插 件 是 使 用 json 编 码 来 输入 和 输出 相应 的 消息 ， 消 息 传递 过 程 中 Logstash 默 认 会 为 消息 编码 内 加 入 相应 的 时 间 惟 和 hostname 等 信息 。 如 果 不 想 要 以 上 信息 (一 般 做 消息 转发 的 情况 
下 ) ， 可 以 使 用 以 下 配置 ， 例 如 : 


output { 
kafka ( 
codec => plain { 
format => "$(message]" 
} 


5.3 logstash-forwarder 


Redis 已 经 帮 有 我 们 解决 了 很 多 的 问题 ， 而 且 也 很 轻 量 ， 为 什么 我 们 还 需要 logstash-for-warder 呢 ? 官方 的 解释 是 : 


Redis provides simple authentication but no transport-layer encryption or 
authorization. This is perfectly fine in trusted environments. However, if 
you're connecting to Redis between datacenters you will probably want to 
use encryption. 


简 而 言 之 : 他 很 好 ， 但 是 他 不 安全 。 


所 以 ， 在 跨 机 房 公 网 环境 中 ， 推 荐 使 用 logstash-forwarder。 


5.3.1 ”Indexer 端 配置 


在 Logstash 作 为 Indexer Server 角 色 的 这 端 ， 我 们 首先 需要 生成 证 书 : 


# cd /etc/pki/tls 
# openssl req -x509 -batch -nodes -days 3650 -newkey rsa:2048 -keyout private/ 
logstash-forwarder.key -out certs/logstash-forwarder.crt 


然后 把 证 书 发 送 到 准备 运行 logstash-forwarder 的 shipper 端 服务 器 上 去 : 


# scp private/logstash-forwarder.key root@target server ip:/etc/pki/tls/private 
# scp certs/logstash-forwarder.crt root@target server ip:/etc/pki/tls/certs 


然后 创建 Logstash 的 配置 文件 。 监 听 部 分 /etc/logstash/conf.d/02-lumberjack-input.conf， 内 容 如 下 : 


input { 
lumberjack { 
port => 5000 
type => “anything” 
SSl certificate => "/etc/pki/tls/certs/logstash-forwarder.crt" 
ssl key => "/etc/pki/tls/private/logstash-forwarder.key" 


以 上 ,我们 在 Logstash 这 端 已 经 配置 完成 。 运 行 logstash-f/etc/logstash/conf.d/ 即 可 。 
Qs 

lumberjack 是 logstash-forwatrder 还 没 用 Golang 重 写 之 前 的 名 字 。 
5.3.2 ”Shipper 端 配置 


我 们 现在 登录 到 我 们 需要 传送 log 的 机 器 上 ， 我 们 已 在 之 前 的 步骤 中 发 送 了 Logstash 的 crt 过 来 。 


1.logstash-forwarder 安 装 


首先 ， 我 们 需要 安装 logstash-forwarder 软 件 。 官 方 都 已 经 提供 了 软件 仓库 可 用 。 在 Redhat 机 器 上 只 需要 添加 一 个 /etc/yum.repos.d/logstash-forwarder.repo， 内 容 如 下 : 


[logstash-forwarder] 

name-logstash-forwarder 
baseurl-http://packages.elasticsearch.org/logstash-forwarder/centos 
gpgcheck-1 


gpgkey-http: / /packages .elasticsearch.org/GPG-KEY-elasticsearch 
enabled-1 


然后 运行 安装 命令 即 可 : 


# yum install -y logstash-forwarder 


2.logstash-forwarder 配 置 


logstash-forwarder 的 配置 文件 是 纯 JSON 格 式 。 


因为 其 轻 量 级 的 设计 目的 ， 所 以 可 配置 项 很 少 。 下 面 是 一 个 /etc/logstash-forwarder 配 置 示例 : 


{ “network” : { "servers" : [ “10.18.10.2:5000” ], “timeout” : 15, "ssl ca" 
fa files" : I 
{ “paths” : [ "/var/log/message" , '"/var/log/secure" 


], "fields" : { "type “syslog” ] 


"/etc/pki/tls/certs/logstash-forwarder.crt" 


"ssl key” : "/etc/pki/tls/private/logstash-forwardei 


我 们 已 完成 了 配置 ， 当 service logstash-forwarder start 之 后 ， 你 就 可 以 在 Kibana 上 看 到 你 的 
3.logstash-forwarder 配 置 说 明 


配置 中 主要 包括 下 面 几 个 选项 。 


志 了 


“ network.servers: 用 来 指定 远 端 ( 即 logstashindexet 角 色 ) 服务 器 的 IP 地 址 和 端口 。 这 里 可 以 写 数 组 ， 但 是 logstash-forwarder 只 会 随机 选 一 台 作为 对 端 发 送 数据 ， 一 直到 对 端 故 障 ， 才 会 重 选 其 他 服务 器 。 


- network.ssl*: 网 络 交互 中 使 用 的 SSL 证 书 路 径 。 


. files.* paths: 读 取 的 文件 路 径 。logstash-forwarder 只 支持 两 种 输入 ， 一 种 就 是 示例 中 用 的 文件 方式 ， 和 Logstash 一 样 也 支持 gob 路 径 ， 即 “/var/log/*log” 这 样 的 写法 ; 一 种 是 标准 输入 ， 写 法 


为 “paths”: ["-"] 


“ files.*.fields: 给 每 条 日 志 添 加 的 固定 字段 ， 相 当 于 Logstash 里 的 add_field 参 数 。 注 意 示 例 中 添加 的 是 type 字 段 。 在 logstash-forwardet 里 添加 的 字段 是 优先 于 LogStash: 
字段 的 。 所 以 ， 在 本 例 中 ， 即 便 你 在 indexetr 上 定义 type 为 “anything”。 事 件 的 实际 type 依 然 是 这 里 添加 的 “syslog”。 


: Inputs: 


这 也 意味 着 ， 你 在 indexer 上 如 果 做 后 续 判 断 ， 应 该 是 这 样 : 


: Lumberjack 配 置 里 定义 的 


filter { 
if [type] — “syslog” { 
grok ( 
match => { “message” => 'S$(SYSLOGTIMESTAMP:syslog timestamp) $(SYSLOGHOST: 


syslog hostname] $(DATA:syslog program) (? 
"d 


D: : N[S(POSINT:syslog pid}\]) ? : 
$(GREEDYDATA:syslog message)" 


Qua 


虽然 SSL 是 可 信任 的 ， 但 是 当 hacket 得 到 你 一 台 机 器 上 的 证 书后 ， 他 可 以 畅通 无 阻 ， 建 议 对 每 台 机 器 都 签发 单独 的 证 书 ， 如 果 你 忙 得 


5.3.3 AIX 上 的 logstash-forwarder-java 


在 AlX 环 境 下 (IBM Power 小 型 机 的 一 种 操作 系统 ) ， 你 无 法 使 用 logstash ( 
是 解决 这 个 问题 的 : https://github.com/didfet/logstash-forwarder-java。 


为 IBM JDK 没 有 实现 相关 方法 ) ， 也 无 法 使 


过 来 的 话 : ) 


logstash-forwarder，github 上 有 个 Logstash-forwarder 再 实现 的 项 目 就 


该 项 目 配置 和 Logstash-forwarder 基 本 保持 一 致 ， 但 是 注意 有 一 个 坑 是 需要 关注 的 ， 作 者 也 在 他 的 github 上 提 到 了 ， 就 是 : 


the ssl ca parameter points to a java keystore containing the root certificate 
of the server, not a PEM file 


不 熟悉 证 书 相关 体系 的 读者 可 能 不 太 清楚 这 个 意思 ， 换 名 话说， 如 果 你 还 按照 logstash-forwarder 的 配置 方法 配置 shipper 端 ， 那 么 你 将 会 得 到 一 个 诡异 的 java.io.IOException: Invalid keystore 


format 异 常 。 


因为 按照 logstash-forwarder-java 的 作者 设计 ，shipper 端 ssl ca 这 个 域 配 置 的 应 该 是 keystore， 


而 不 是 PEM ， 因 此 需 


从 你 生成 的 crt 中 创建 出 keystore (ks) 文件 ， 命 令 如 下 : 


# keytool -importcert -trustcacerts -file logstash-forwarder.crt -alias ca - 
keystore keystore.jks 


一 个 示例 的 shipper.conf 为 : 


{ 


“network” : { 
“servers” : [ “192.168.1.1:5043” ], 
“ssl ca : “/mnt/disk12/logger/logstash/config/keystore.jks” 
j 
ffiles” : [ 
{ 
“paths” : [ “/mnt/disk12/logger/logstash/config/2.txt” ], 
"fields" : ( “type” : “sadb” } 


} 
] 
} 


server 可 以 配置 多 个 ， 这 样 如 果 一 个 logstash server 连 不 上 可 以 连 下 一 个 。 


其 余 配 置信 息 ， 请 参考 logstash-forwarder， 它 完全 兼容 。 


配置 好 以 后 启动 它 即 可 : 


# java -jar logstash-forwarder-java-0.2.3-SNAPSHOT.jar -quiet -config 
logforwarder.conf 


注意 ， 该 程序 实际 在 以 下 环境 验证 可 


AIX (6100-04-06-1034) 

java version “1.6.0” 

Java (TM) SE Runtime Environment (build pap6460sr14-20130705 01 (SR14) ) 

IBM J9 VM (build 2.4, JRE 1.6.0 IBM J9 2.4 AIX ppc64-64 jvmapó460srl4- 
20130704 155156 (JIT enabled, AOT enabled) 

J9VM - 20130704 155156 

JIT - r9 20130517 38390 

GC - GA24 Java6 SR14 20130704 1138 B155156) 

JCL - 20130618 01 


5.4 Rsyslog 


Rsyslog 是 RHEL6 开 始 的 默认 系统 Syslog 应 用 软件 (当然 ，RHEL 自 带 的 版 本 较 低 ， 实 际 官方 稳定 版 本 已 经 到 v8 了 ) 。 官 网 地 址 : http://www.rsyslog.com 


目前 Rsyslog 本 身 也 支持 多 种 输入 输出 方式 ， 内 部 逻辑 判断 和 模板 处 理 。 其 内 部 架构 如 图 5-1 所 示 。 
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图 5-1 Rsyslog 架 构 


Ptcp 
auditd 


gssapi 


kmsg 


5.4.1 ”常用 模块 介绍 


不 同 模 块 插 件 在 rsyslog 流 程 中 发 挥 作用 的 原理 ， 可 以 阅读 : http://www.rsyslog.com/doc/master/configuration/modules/workflow.html。 


流程 中 可 以 使 用 mmnormalize 组 件 来 完成 数据 的 切 分 (相当 于 logstash-filter-grok 功 能 ) 。 


Rsyslog 从 v7 版 本 开始 带 有 omelasticsearch 插 件 可 以 直接 写 入 数据 到 Elasticsearch 集 群 ， 配 合 mmnormalize 的 使 用 示例 见 : http://puppetlabs.com/blog/use-rsyslog-and-elasticsearch-powerful- 


log-aggregation。 


而 normalize 语 法 说 明 见 : http://www.liblognorm.com/files/manual/index.htmlsampleda-tabase.htm 


类 似 的 还 有 mmfields 和 mmjsonparse 组 件 。 注 意 ，mmjsonparse 要 求 被 解析 的 MSG 必须 以 @CEE: 开头 ， 解 析 之 后 的 字符 串 为 JJON。 使 用 示例 
W: http;//blog.sematext.com/2013/05/28/structured-logging-with -rsyslog-and-elasticsearch/, 


此 外 ，Rsyslog 从 v6 版 本 开始 ， 设 计 了 一 套 rainerscript 作 为 配置 中 的 DSL。 利 用 rainerscript 中 的 函数 ， 也 可 以 做 到 一 些 数据 解析 和 逻辑 判断 : 


* tolower 


“Cstr 


* cnum 


“ wrap 


* replace 

- field 

* re. extract 

- re match 

* contains 

' if-else 

* foreach 

: lookup 

* set/reset/unset 


详细 说 明 见 http://www.rsyslog.com/doc/v8-stable/rainerscript/functions.html。 


54.2 与 Logstash 合 作 


发 全 


在 复杂 条 件 下 远 比 不 上 完整 的 正则 引擎 。 


那么 ， 怎 么 使 用 Rsyslog 作 为 日 志 收 集 和 传输 组 件 ， 来 配合 Logstash 工 作 呢 ? 


如 果 只 是 简单 的 Syslog 数 据 ， 直 接 单 个 Logstash 运 行 即 可 ， 配 置 方式 见 本 书 前 面 2.4 节 。 


虽然 Rsyslog 很 早 就 支持 直接 输出 数据 给 Elasticsearch ， 但 如 果 你 使 用 的 是 v8.4 以 下 的 版 本 ， 我 们 这 里 并 不 推荐 这 种 方式 。 


为 normalize 语 法 还 是 比较 简单 ， 只 支持 时 间 、 字 符 串 、 数 字 、IP 地 址 等 几 


如 果 你 运行 着 一 个 高 负荷 运行 的 Rsyslog 系 统 ， 每 秒 传输 的 数据 远大 过 单个 Logstash 能 处 理 的 能 力 ， 你 可 以 运行 多 个 Logstash 在 多 个 端口 ， 然 后 让 Rsyslog 做 轮训 转发 (事实 上 ， 单 个 omfwd 本 身 的 转 


6 力也 有 限 ， 所 以 推荐 这 种 做 法 ) : 


Ruleset ( name= "forwardRuleSet" ) { 
Action ( type= “mmsequence” mode= “instance” 
if $.seq — “0” then { 
action (type= “omfwd” 


from- “0” to- “4” var- "$.seq" 


Target- “127.0.0.1” Port- “5140” Protocol- "tcp" 


“150000” queue.dequeuebatchsize- "2000" ) 
} 
if $.seq 一 “1” then { 
action (type= “omfwd” Target- “127.0.0.1” Port- “5141” Protocol- "tcp" 


size- “150000” queue.dequeuebatchsize- “2000” ) 

H 

if $.seq = “2” then { 
action (type= “omfwd” 


Target- “127.0.0.1” Port- “5142” 
queue.size- "150000" 


queue.dequeuebatchsize- "2000" ) 


Protocol- "tcp" 


} 
if $.seq = “3” then { 
action (type= “omfwd” 


Target= “127.0.0.1” Port- “5143” 
queue.size- “150000” 


queue.dequeuebatchsize- "2000" ) 


Protocol- "tcp" 


) 


queue.size- 


queue. 


如 果 Rsyslog 仅 是 作为 Shipper 角 色 运 行 ， 环 境 中 有 单独 的 消息 队列 可 


54.3 Mmexternal 模 块 


如 果 你 使 


，Rsyslog 也 有 对 应 的 omkafka、omredis、omzmq 插 件 可 用 。 


的 是 v8.4 及 以 上 版 本 的 rsyslog， 其 中 有 一 个 新 加 入 的 Mmexternal 模 块 。 该 模块 是 在 v7 的 omprog 模 块 基础 上 发 


来 ， 而 Rsyslog 接 收 到 这 个 输出 再 进行 下 一 步 处 理 ， 这 就 解决 了 前 面 提 到 的 “normalize 语 法 太 简单 ”的 问题 ! 


下 面 是 使 


Rsyslog 配 置 如 下 : 


Rsyslog 的 Mmexternal 和 omelasticsearch 完 成 Nginx 访 问 日 志 直 接 解析 存储 的 配置 。 


展 出 来 的 ， 可 以 让 你 使 用 任意 脚本 ， 接 收 标准 输入 ， 自 行 处 理 以 后 再 输出 回 


module (load- 'imuxsock' SysSock.RateLimit.Interval= “0” ) 
module (load- "mmexternal" ) 
module (load- "omelasticsearch' ) 
template (name= "logstash-index' type= “list” ) ( 
constant (value= "logstash-" ) property (name= "timereported' dateFormat- 
“rfc3339” position.from- “1” position.to- '4" ) 
constant (value= “.” ) property (name= "timereported" 
position.from- “6” position.to- "7" ) 
constant (value- "." ) property (name- "timereported" 
position.from- “9” position.to- "10" ) 


dateFormat= "rfc3339" 


dateFormat= "rfc3339" 


} 

template ( name= "nginx-log' type= “string” string- “%msg%\n” ) 

if ( $syslogfacility-text == 'local6' and $programname startswith 'www-access-' 
and not ($msg contains '/2/remind/unread count' or $msg contains '/2/ 
remind/group unread ') ) then 7 


action ( type= “mmexternal” binary= “/usr/local/bin/rsyslog-nginx- 

elasticsearch.py' interface.input- “fulljson” forcesingleinstance= “on” 
action ( type= “omelasticsearch” 

template= “nginx-log” 

server- “eshost .example.com” 

bulkmode= “on” 

dynSearchIndex- "on" 

searchIndex- "logstash-index" 

searchType- "nginxaccess" 

queue.type- "linkedlist" 

queue.size- "50000" 

queue.dequeuebatchsize- “5000” 

queue.dequeueslowdown- “100000” 


) 


stop 
l 
其 中 调用 的 Python 脚本 示例 如 下 (注意 只 是 做 示例 ， 脚 本 中 的 split 功 能 其 实 可 以 用 Rsyslog 的 Mmfields 揪 件 完成 ) : 


) 


#!/usr/bin/pypy 
import sys 
import json 
import datetime 


def nginxLog (data) : 
hostname = data['hostname'] 
logline = data['msg'] 


time local, request, http user agent, staTus, remote addr, http referer, 


request time, body bytes sent, http x forwarded proto, http x 
forwarded for, http host, http cookie, upstream response | time - 
logline.split ( * 
try: 
upstream response time = float (upstream response time) 
except: 
upstream response time - None 
method, uri, verb - request.split ( 
arg = () 
try: 
url path, url args = uri.split ( '?' ) 
for args in url args.split ( '&' ) : 


6r) 


k, v = args.split ( =” ) 
arg[k] = 
except: 
url path = uri 
# Why $z do not implement? 
ret = ( "Gtimestamp" 3 datetime.datetime.strptime (time local, 
40800] “) . strftime $FT£T«-0800' ) , “host” : hostname, "method" 


} 
return ret 
def onInit () : 
Do everything that is needed to initialize processing" 
Def onReceive (msg) : 
data = json.loads (msg) 
ret = nginxLog (data) 
print json. dumps, ({'msg' 
def onExit () : 
Do everything that is needed to, finish processing. This is being called 
immediately before exiting. 
# most often, nothing to do here 
onInit () 
keepRunning = 
while keepRunning 一 1: 
msg = sys.stdin.readline () 
if msg: 
msg = msg[:len (msg) -1] 
onReceive (msg) 
sys.stdout.f?lush () 
else: 
keepRunning = 
onExit () 
sys.stdout.f?lush () 


: ret}) 


' [Sd/Sb/SY:$H:9M:$8 
: method.lstrip ( 


), " url path 


": url pati 


h,” url args ": arg," verb ": verb.rstrip ( ' ' ) , "http use 


注意 输出 的 时 候 ， 


顶层 的 key 是 不 能 变 的 ，msg 还 得 叫 msg， 如 果 是 hostname 还 得 叫 hostname， 等 等 。 否 则 ，Rsyslog 会 当做 处 理 无 效 ， 直 接 传递 原 有 数据 内 容 给 下 一 步 。 


Mmexternal 是 基于 direct mode 的 ， 所 以 如 果 你 发 送 的 数据 量 较 大 时 ，Rsyslog 并 不 会 像 linkedlist mode 那 样 缓冲 在 磁盘 队列 上 ， 而 是 持续 fork 出 新 的 Mmexternal 程 序 ， 几 和 干 个 进程 后 ， 你 的 服务 器 
MT! ! 所 以 ,务必 开启 forcesingleinstance 选 项 


5.5 Nxlog 


pm 


Tr. 


其 内 部 支持 使 有 


CC 语言 写 的 一 个 跨 平台 


志 收 集 处 理 软件 。 


Nxlog 是 


Nxlog 的 Windows 安 装 文件 下 载 地 址 见 
Nxlog 默 认 配置 文件 位 置 在 : C: \Program Files (x86) \nxlog。 


配置 文件 中 有 3 个 关键 设置 ， 分 别 是 : input (日 志 输 入 端 ) 、output (日 志 输出 端 


假设 我 们 有 两 台 服务 器 : 
* Logstash 服 务 器 IP 地 址 : 192.168.1.100 


- windows 服 务 器 IP 地 址 : 192.168.1.101 


收集 其 中 的 Windows 事 务 日 志 的 配置 如 下 所 示 。 


1.Logstash 配 置 文件 


Perl 正 则 和 语法 来 进行 数据 


结构 化 和 逻辑 判断 操作 。 不 过 ， 


: http;//nxlog.org/system/files/products/files/1/nxlog-ce-2.8.1248.msi 


route ( 绑 定 某 输入 到 


最 常用 的 场景 。 是 在 Windows 服 务 器 上 ， 作 为 Logstash 的 替代 品 运 


体 某 输出 ) 。 


input { 
tcp ( 
port => 514 
} 
} 
output{ 
elasticsearch { 
host => “127.0.0.1” 
port => “9200” 
protocol => “http” 


2.Nxlog 配 置 文件 


XInput testfile» 
Module im file 
File “C:\\test\\\*. log” 
SavePos TRUE 
</Input> 
«Output out» 
Module om tcp 


Host —192.168.1.100 
Port 514 
«/Output» 
«Route 1» 
Path testfile -» out 
«/Route» 


配置 文件 修改 完毕 后 ， 重 启 服务 即 可 ， 如 图 5-2 所 示 。 
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图 5-2 nxlog 服 务 


Heka 是 Mozilla 公 司 仿照 Logstash 设 计 ， 上 


Golang 重 写 的 一 个 开源 项 目 。 


同样 采 F 


设计 了 sandbox 概 念 ， 可 以 采 


官网 地 址 见 : http://hekad.readthedocs.org/。 


下 面 是 同样 的 处 理 逻 辑 ， 通 过 Syslog 接 收 Nginx 访 问 


内 嵌 Lua 脚 本 做 这 一 部 分 的 工作 ， 降 低 了 全 程 使 


了 input->decoder->filter->encoder->output 的 流程 概念 。 其 特点 在 于 ， 在 中 间 的 decoder/filter/encoder 部 
静态 Golang 编 写 的 难度 。 此 外 ， 其 filter 阶 段 还 提供 了 一 些 监控 和 统计 报警 功能 。 


i, 解析 并 存储 进 Elasticsearch，heka 配 置 文 件 如 下 : 


[hekad] 
maxprocs = 48 
[TcpInput] 
address = ^":514 
parser type = "token" 
decoder = "shipped-nginx-decoder" 
[shipped-nginx-decoder] 
type = "MultiDecoder" 
subs = ['RsyslogDecoder' r 
cascade strategy = “all” 
log : sub errors - true 
[RsyslogDecoder] 
type - "SandboxDecoder" 
filename = "lua decoders/rsyslog.lua" 
[RsyslogDecoder. config] 
type = “nginx. access" 
template = Sri $2$TIMESTAMP$ $HOSTNAME$ $syslogtag$$msg::: 
msg: : :drop-last-lf$An' 
tz = "Asia/Shanghai" 
[nginx-access- decoder] 
type = "SandboxDecoder" 
filename = “lua decoders/nginx access.lua" 
[Inginx-access- decoder.config] 
type = "combined" 
user agent | transform = true 
log : format = '[$time local]'$http x up calling : line ; id 
agent" ^$staTus'[$remote addr]* Shttp : x log 1 uid" 


'nginx-access-decoder'] 


"$request" 
"Shttp referer" 


:sp-if-no-1st-sp$$ 


` "Shttp user - 
^$request | 


time'$body bytes sent'$http x forwarded proto $http x forwarded for'$request | 


uid'$http host' $http « cookie'$upstream response time" 
[ESLogstashVOEncoder] 
es index : from | timestamp = true 


fields- [ “Timestamp” , “Payload, “Hostname, “Fields” ] 
type_name = %{Type}” 

[ElasticSearchOutput] 

message matcher 一 "Type — 'nginx.access '" 

server = "http: //eshost. example.com: 9200" 

encoder = "ESLogstashVOEncoder" 


f?lush interval = 50 
f?lush count = 5000 


Heka 目 前 仿照 的 还 是 旧版 本 的 Logstash schema 设 计 ， 所 有 切 分 字段 都 存储 在 @fields 下 。 


经 测试 ， 其 处 理性 能 跟 开 启 了 多 线程 filters 的 Logstash 进 程 类 似 ， 都 在 每 秒 30000 条 。 


5.7 Fluentd 


Fluentd 是 另 一 个 Ruby 语 言 编写 的 日 志 收集 系统 。 和 Logstash 不 同 的 是 ，Fluentd 是 基于 MRI 实现 的 ， 并 不 是 利用 多 线程 ， 而 是 利用 事件 驱动 。 


Fluentd 的 开发 和 使 用 者 ， 大 多 集中 在 日 本 。 


571 配置 示例 


Fluentd 受 Scribe 影 响 颇 深 ， 包 括 节点 间 传 输 采 用 磁盘 buffer 来 保证 数据 不 丢失 等 的 设计 ， 也 包括 配置 语法 。 下 面 是 一 段 配置 示例 : 


«source» 
type tail 
read from head true 
path /var/lib/docker/containers/*/*-json.log 
pos file /var/log/fluentd-docker.pos 
time format $Y-$m-SdT$H:$M:$S 
tag docker.* 
format json 
</source> 
# Using filter to add container IDs to each event 
<filter docker.var.lib.docker.containers.*.*.log» 
type record transformer 
<record> T 
container id ${tag parts[5]} 
«/record» 
«/filter» 
«match docker.var.lib.docker.containers.*.*.log» 
type copy 
«store» 
# for debug (see /var/log/td-agent.log) 
type stdout 
</store> 
<store> 
type elasticsearch 
logstash_format true 
host “#{ENV['ES PORT 9200 TCP ADDR']) 
link feature pii 
port 9200 
flush interval 5s 
«/store» ™ 
«/match» 


# dynamically configured to use Docker's 


注意 ， 虽 然 示例 中 演示 的 是 tail 方 式 。Fluentd 对 应 用 日 志 ， 并 不 推荐 如 此 读 取 。Fluentd 为 各 种 编程 语言 提供 了 客户 端 库 ， 应 用 可 以 直接 加 载 日 志 库 发 送 日 志 。 下 面 是 一 个 PHP 应 用 的 示例 : 


hi 


«?php 

require once DIR .'/src/Fluent/Autoloader.php'; 

use Fluent\Logger\FluentLogger; 

Fluent\Autoloader: : register () ; 

$logger = new FluentLogger ( “unix:///var/run/td-agent/td-agent.sock” ) ; 

$logger->post ( "fluentd.test.follow' , array ( “from” => "userA' , “to” => "userB' ) ) ; 


Fluentd 使 用 如 下 配置 接收 即 可 : 


«source» 
type unix 
path /var/run/td-agent/td-agent.sock 
</source> 
<match fluentd.test.**» 
type forward 
send timeout 60s 
recover wait 10s 
heartbeat interval 1s 
phi threshold 16 
hard timeout 60s 
«server» 
name myserverl 
host 192.168.1.3 
port 24224 
weight 60 
«/server» 
«server» 
name myserver2 
host 192.168.1.4 
port 24224 
weight 60 
«/server» 
«secondary» 
type file 
path /var/log/f?luent/forward-failed 
«/secondary» 
«/match» 


5.7.2 ”Fluentd 揪 件 


作为 用 动态 语言 编写 的 软件 ，Fluentd 也 拥有 大 量 插件 。 每 个 插件 都 以 RubyGem 形 式 独 立 存 在 。 事 实 上 ，Logstash 在 这 方面 就 是 学 习 Fluentd 的 。 安 装 方式 如 下 : 


/usr/sbin/td-agent-gem install fluent-plugin-elasticsearch fluent-plugin-grok parser 


fluentd 插 件 列表 见 : http://www.fluentd.org/plugins, 


5.8 Message: : Passing 


Message: : Passing 是 一 个 仿照 Logstash 写 的 Perl5 项 目 。 项 目 早 期 甚至 就 直接 照 原 样 也 叫 “Logstash” 的 名 字 。 


但 实际 上 ，Message: : Passing 内 部 原理 设计 还 是 有 所 偏差 的 。 这 个 项 目 整个 基于 AnyEvent 事 件 驱动 开发 框架 ( 即 著名 的 libev 库 ) 完成 ， 也 要 求 所 有 插件 不 要 采取 阻塞 式 编程 。 所 以 ， 虽 然 项 
不 太 活跃 ， 播 件 接口 不 甚 完善 ， 但 是 性 能 方面 却 非常 棒 。 这 也 是 我 从 多 个 Per 日志 处 理 框架 中 选择 介绍 这 个 的 原因 。 


Message: : Passing 有 比较 全 的 input 和 output 播 件 ， 这 意味 着 它 可 以 通过 多 种 协议 跟 Logstash 混 跑 ， 不 过 filter 揪 件 比 较 缺 乏 。 对 等 于 grok 的 插件 叫 Message: : Passing: : Filter: : 
Regexp (我 写 的 ， 嘿 嘿 ) 。 下 面 是 一 个 完整 的 配置 示例 : 


use Message::Passing::DSL; 
run message server message chain ( 
output stdout => ( 
Class -2'STDOUT', 


output elasticsearch => ( 
class -»'ElasticSearch', 
elasticsearch servers => ['127.0.0.1:9200'], 


encoder ( “encoder” , 

class -»'JSON', 

output to -»'stdout', 

output to -»'es', 

) 5 

filter regexp => ( 

Class -»'Regexp', 

format -»':nginxaccesslog', 

capture => [qw ( ts status remotehost url oh responsetime upstreamtime bytes ) ] 

output to -»'encoder', 

) 5 

filter logstash => ( 
class -»'ToLogstash', 
output to —»'regexp', 


decoder decoder => ( 
class -»'JSON', 
output to -»'logstash', 
) 5 
input file => ( 

class -»'FileTail', 
output to -»'decoder', 
) ; 
H 


$868: ”Logstash 源 码 解析 


本 章 试 图 讲解 Logstash 源 码 中 的 关键 点 ， 帮 助 大 家 快速 上 手 开发 自己 的 Logstash 插 件 。 不 过 在 开始 之 前 ， 或 许 要 先 解释 一 个 问题 : Logstash 和 过 去 很 多 日 志 收集 系统 比 ， 优 势 就 在 于 其 源码 是 用 Ruby 
写 的 ， 所 以 插件 开发 相当 容易 。 大 多 数 框架 都 用 Java 写 ， 毕 竟 做 大 规模 系统 Java 有 天 生 优 势 。 而 另 一 个 新 生 代 Fluentd 则 是 标准 的 Ruby 产 品 ( 即 Matz's Ruby Interpreter) 。Logstash 为 什么 选用 JRuby 来 
实现 ， 似 乎 有 点 两 头 不 讨好 啊 ? 


乔丹 . 西 塞 曾经 多 次 著 文 聊 过 这 个 问题 。 为 了 避 凑 字数 的 嫌疑 ， 这 里 罗列 他 的 gist 地 址 : 


- “Time sucks" (https://gist.github.com/jordansissel/2929216) 一 文 是 关于 Time 对 象 的 性 能 测试 ， 最 快 的 生成 方法 是 sprintf 方 法 ，MRI 性 能 为 82600 call/sec, JRuby1.6.7 22131000 call/sec， 而 JRuby1.7.0 为 
215000 call/sec。 


. "Comparing egexp patterns speeds" (https:/ /gist.github.com/jordansissel/1491302) 一 文 是 关于 正则 表达 式 的 性 能 测试 ， 使 用 的 正则 统一 为 (-mix: C C AW CNN) +) 90) ， 结 果 MRI1.9.2 为 
530000 matches/sec， 而 JRuby1.6.5 为 690000 matches/sec。 


© “Logstash performance under ruby” (https://gist.github.com/jordansissel/4171039) 一 文 是 关于 Logstash 本 身 数 据 流转 性 能 的 测试 ， 使 用 logstash-input-generator 插 件 生成 数据 ，logstash-output-stdout 到 pv 工 
具 记 点 统计 。 结 果 MRI1.9.3 为 4000 events/sec， 而 JRuby1.7.0 为 25000 events/sec。 


可 能 你 已 经 运行 着 Logstash 并 发 现 自己 的 线 上 数据 远 超 过 这 个 测试 一 一 这 是 因为 乔丹 . 西 塞 在 2013 年 之 前 ， 一 直 是 业余 时 间 开发 Logstash， 而 且 从 未 用 在 自己 线 上 过 。 所 以 当时 的 很 多 测试 是 在 他 自己 
电脑 上 完成 的 。 


在 Logstash 得 到 大 家 强烈 关注 后 ， 作 者 发 表 了 “logstash needs full time love" — (https:;//gist.github.com/jordansissel/3088552) ， 表 明了 这 点 并 求 一 份 可 以 让 自己 全 职 开 发 Logstash 的 工作 ， 同 
时 列 出 了 1.1.0 版 本 以 后 的 roadmap。 (不 过 事实 证 明 当 时 作者 列 出 来 的 这 些 需 求 其 实 不 紧急 ， 因 为 大 多 数 ， 或 者 说 除了 Kibana 以 外 ， 至 今 依然 没有 ==! ) 


时 间 轴 继续 向 前 推 ， 到 2011 年 ， 你 会 发 现 Logstash 原 先 其 实 也 是 用 MRI1.8.7 写 的 ! 在 grok 模 块 从 C 扩 展 改 写成 FFI 扩 展 后 (https://code.google.com/p/logstash/issues/detailid=37) ， 才 正式 改 | 
JRuby。 


切换 语言 的 当时 ， 乔 丹 . 西 塞 发 表 了 “logstash，why jruby” (https:;//gist.github.com/jordansissel/978956) 大 家 可 以 一 读 。 


有 实 上 ， 时 至 今日 ， 多 种 Ruby 实 现 的 痕迹 (到 处 都 有 RUBY_ENGINE 变 量 判断 ) 依然 遍布 Logstash 代 码 各 处 ， 作 者 也 力图 保证 尽 可 能 多 的 代码 能 在 MRI 上 运行 。 


在 和 插件 无 关 的 核心 代码 中 ， 只 有 LogStash: : Event 里 生成 @timestamp 字 段 时 用 了 Java 的 joda 库 为 JRuby 仅 有 的 。 稍 微 修改 成 Ruby 自 带 的 Time 库 ， 即 可 在 MRI 上 运行 起 来 。 而 主要 插件 中 ， 也 只 有 
logstash-filter-date 和 logstash-output-elasticsearch 是 Java 相 关 的 。 


不 过 ，Logstash 被 Elastic co 收购 以 后 ， 又 有 另 一 种 讨论 中 的 发 展 方向 ， 就 是 把 Logstash 的 core 部 分 代码 ， 尽 量 JVM 通 用 化 ， 未 来 ， 可 以 用 JRuby、Jython、scala、Groow、Cclojure 和 Java 等 任意 
JVM 平 台 语言 写 Logstash 插 件 。 


这 就 是 开源 软件 的 多 样 性 可 能 。 在 我 们 拭目以待 的 同时 ， 尽 量 了 解 源码 实现 ， 积 极 参与 到 开源 社区 ， 也 是 对 自己 能 力 的 一 种 提升 。 本 章 包括 Logstash 源 码 中 两 个 键 点 : 1) Pipeline，Logstash 主 流 流 
程 的 称呼 也 是 其 核心 代码 的 所 在 文件 名 ， 本 章 带 你 走 进 Pipeline， 了 解 Logstash 设 计 思想 。2) Plugins， 介 绍 插件 设计 中 两 个 重要 环节 ，Event 人 怎么 来 ， 并 发 怎么 实现 。 


6.1 Pipeline 


在 一 开始 ， 就 介绍 过 ，Logstash 对 日 志 的 处 理 ， 从 Input 到 Output， 就 像 在 Linux 命 令 行 上 的 管道 操作 一 样 。 事 实 上 ， 在 Logstash 中 ， 对 此 有 一 个 专门 的 名 词 ， 叫 Pipeline。 


pipeline 的 代码 加 载 路 径 如 下 : 


bin/logstash -»lib/logstash/runner.rb -»lib/logstash/agent.rb ->lib/logstash/ 
pipeline.rb 


这 个 最 关键 的 pipeline.rb， 可 以 归纳 成 下 面 这 么 一 段 缩 略 版 的 代码 : 


output 发 生 堵 塞 ， 都 会 一 直 


Gconfig = grammar.parse (configstr) 
code = Gconfig.compile 
eval (code) 
Ginput to filter = SizedQueue.new (20) 
Gfilter to output = SizedQueue.new (20) 
Gsettings = { 

“filter-workers” => 1, 


} 
Qinput threads = [] 
@inputs.each do |input| 
Ginput threads << Thread.new ( input.run (@input to filter) 
end 


Gfilter threads = 8settings[ "filter-workers" ].times.collect do 


Thread.new { 
begin 
while true 
event = Qinput to filter.pop 
events = [] 7 7 
filter (event) { |newevent| events << newevent } 
events.each { |event| (filter to output.push (event) 
end NS 
end 
l 
end 
Gflusher lock - Mutex.new 


} 


@flusher thread = Thread.new ( Stud.interval (5) { Gflusher lock.synchronize { @input_ 


^to filter.push (FLUSH EVENT) ) ) ) 
Goutput threads = [ ul 
Thread.new { 
Goutputs.each (&:worker setup) 
while true 
event = QGfilter to output.pop 
output (event) 
end 
} 
] 
Ginput threads.each (&:join) 
Gfilter threads.each (&:join) 
Goutput threads.each (&:join) 


这 是 整个 缩 略 版 ， 可 以 了 解 到 一 个 关键 信息 ， 对 我 们 理解 Logstash 原 理 是 最 有 用 的 : Ginput to filter 和 @filter to_output， 都 是 一 个 固定 大 小 为 20 的 线程 安全 的 数组 。 所 以 ， 任 意 一 个 filter 或 者 


6.2 Plugins 


除了 上 节 介 绍 的 pipeline，Logstash 中 还 有 几 个 重要 概念 : 事件 (event) , fft (plugin) ， 并 发 线程 (worker) 等 。 这 些 显 


堵塞 到 最 前 端的 接收 。 这 也 是 logstash-input-heartbeat 的 理论 基础 。 


阶段 的 插件 代码 中 完成 。 下 面 介绍 这 几 个 概念 ， 是 如 何在 input 和 output 插 件 中 实现 的 。 


6.2.1 Input 中 的 Codec 


上 一 节 大 家 可 能 注意 到 了 ， 整 个 Pipeline 非 常 简单 ， 无 非 就 是 一 个 多 线程 的 线程 间 数 据 读 写 。 但 是 ， 之 前 介绍 的 Codec 在 哪里 ? 我 们 可 以 看 到 Filter 阶 段 的 pop 操 作 ， 但 是 Ev 
@input to filter 的 呢 ? 这 两 个 问题 ， 并 不 在 Pipeline 中 完成 ， 而 是 Plugin 中 。 


Logstash 从 1.5 开 始 ， 把 各 个 Plugin 拆 分 成 了 单独 的 gem， 主 代码 里 只 留 下 了 几 个 base.rb 类 。 所 以 ， 要 了 解 详 细 情 况 ， 我 们 需要 阅读 一 个 实际 跑 数据 的 插件 ， 比 如 
vendor/bundle/jruby/1.9/gems/logstash-input-file-0.1.6/lib/logstash/inputs/file.rb, 


可 以 看 到 其 中 最 关键 的 读 取 数据 部 分 代码 如 下 : 


然 在 上 节 讲 解 的 pipeline.rb 中 ， 并 没有 体现 。 


dipl 


有 实 上 ， 它 们 分 布 在 不 同 


ent 又 是 怎么 进 


hostname = Socket.gethostname 
Gtail.subscribe do |path, line| 


Glogger.debug? && G(logger.debug ( "Received line" , :path => path, :text => line) 


Gcodec.decode (line) do |event| 
decorate (event) 


event[ "host" ] = hostname if !event.include? ( “host” ) 
event[ "path" ] - path 
queue «« event 
end 
end 


这 里 有 两 个 关键 函数 : GCcodecdecode (line) 和 decorate (event) , 


@codec 在 base.rb 中 默认 为 plain， 那 么 我 们 就 继续 看 vendor/bundle/jruby/1.9/gems/logstash-codec-plain-0.1.5/lib/logstash/codecs/plain.rb 的 相关 部 分 : 


def register 
Gconverter = LogStash::Util::Charset.new (@charset) 
Gconverter.logger = @logger 

end 

public 

def decode (data) 


yield LogStash::Event.new ( "message" => converter.convert (data) ) 


end 4 def decode 


超 简 短 。 就 是 在 这 个 @codec.decode (line) 里 ， 生 成 了 LogStash : 


继续 看 lib/logstash/event.rb 的 内 容 : 


: Event 对 象 。 那 么 ， 我 们 通过 output{codec= >rubydebug} 看 到 的 除了 message 字 段 以 外 的 那些 数 


居 ， 又 是 怎么 来 的 呢 ? 


y 
TIMESTAMP "Qtimestamp" 
VERSION "Qversion" 
VERSION ONE - "1" 
TIMESTAMP FAILURE TAG = ^" timestampparsefailure" 
TIMESTAMP FAILURE FIELD = ^ Gtimestamp" 
public 
def initialize (data = {}) 
Glogger = Cabin::Channel.get (LogStash) 
Gcancelled - false 
Gdata = data 
Gaccessors = LogStash::Util::Accessors.new (data) 
Gdata[VERSION] ||- VERSION ONE 
Gdata[TIMESTAMP] = init timestamp (@data [TIMESTAMP] ) 


CHAR PLUS 


现在 就 清楚 了 ， 这 个 特殊 的 @timestamp 是 在 event 对 象 初始 化 的 时 候 加 上 的 ， 其 实现 为 : 


private 
def init timestamp (o) 


begin 
timestamp = o ? LogStash::Timestamp.coerce (0) : LogStash::Timestamp.now 


再 看 lib/logstash/timestamp.rb 中 的 实现 : 


class Timestamp 
def initialize (time = Time.new) 
Gtime = time.utc 
end 
def self.now 
Timestamp.new (: : Time.now) 
end 


这 就 是 我 们 看 到 Logstash 生 成 的 事件 总 是 UTC 时 区 时 间 的 原因 。 


至 于 如 果 一 开始 就 传 入 了 @timestamp 数 据 的 处 理 ， 则 是 这 样 : 


JODA ISO8601 PARSER = org.joda.time.format.ISODateTimeFormat.dateTimeParser 
UTC = org.joda.time.DateTimeZone.forID ( "UTC" ) 
def self.parse iso8601 (t) 

millis = JODA ISO8601 PARSER.parseMillis (t) 

LogStash::Timestamp.at (millis / 1000, (millis $ 1000) * 1000) 
def self.coerce (time) 

case time 

when String 

LogStash::Timestamp.parse iso8601 (time) 


同样 会 利用 oda 库 做 一 次 解析 ， 还 是 转换 成 UTC 时 区 。 


6.2.2 Output 中 的 Worker 


我 们 知道 ，Logstash 中 ， 命 令 行 的 -w 参 数 是 设置 filter 插 件 的 线程 数 的 ， 而 在 Output 揪 件 配置 中 ， 很 多 都 另外 有 一 个 Workers 选 项 。 这 是 从 lib/logstash/ouput/base.rb 中 继承 来 的 。 其 在 Pipeline 中 ， 
是 通过 这 行 @outputs.each (&: worker setup) 调用 的 。 


worker_setup 函 数 实现 如 下 : 


define singleton method (: handle, method (: handle worker) ) 
Gworker queue = SizedQueue.new (20) T 
Gworker plugins = @workers.times.map { self.class.new (params.merge ( “workers” => 1, 
"codec" => G8codec.clone) ) } 
Gworker plugins.map.with index do |plugin, i| 
Thread.new (original params, Gworker queue) do |params, queue| 
LogStash::Util::set thread name ( "»f(self.class.config name].f(i)" ) 
plugin.register 
while true 
event = queue.pop 
plugin.handle (event) 
end 
end 
end 


第 一 行 定义 了 单 例 方法 handle_ worker， 其 具体 实现 是 : 


def handle worker (event) 
Gworker queue.push (event) 
end 


也 就 是 说 ，output 阶 段 在 worker_setup 这 里 ， 对 每 个 “可 以 运行 多 线程 ， 且 确实 配置 了 多 线程 ”的 output 揪 件 ， 单 独 准备 一 个 依然 固定 大 小 20 的 线程 安全 数组 。 然 后 ，pipeline 从 @filter to output 
拿 到 的 数据 ， 再 推进 单个 插件 的 @worker_queue 里 ， 由 多 线程 来 获取 。 


第 7 章 “插件 开发 


要 讲解 内 容 包括 : 插件 格式 ;插件 的 关 


前 面 已 经 提 过 在 运行 Logstash-1.4.2 的 时 候 ， 可 以 通过 --pluginpath 参 数 来 加 载 自己 写 的 插件。 那么 ， 播 件 又 该 怎么 写 呢 ? 本 章 就 给 大 家 介绍 这 方面 的 知识 ， 
键 方法 ， 介 绍 Logstash 不 同类 型 的 插件 ， 从 各 自 的 基 类 继承 的 各 自 所 需 的 接口 方法 ; 播 件 打包 ; 插件 示例 : Filter、Input 和 Output 开 发 示例 。 


7.1 插件 格式 


Logstash 不 单 在 配置 文件 上 提供 了 DSL， 在 插件 实现 上 同样 提供 了 DSL。 本 节 介 绍 Logstash 插 件 的 DSL。 


一 个 标准 的 logstash-input 输 入 插件 格式 如 下 : 


require 'logstash/namespace' 
require 'logstash/inputs/base' 
class LogStash::Inputs::MyPlugin < LogStash::Inputs::Base 
config name 'myplugin' 
milestone 1 
config :myoption key, :validate -»:string, :default -»'myoption value" 
public def register i 
end 
public def run (queue) 
end 
end 


其 中 大 多 数 语句 在 过 滤器 和 输出 阶段 是 共有 的 ， 参 数 说 明 如 下 : 
“ config name: 用 来 定义 该 插件 写 在 Logstash 配 置 文件 里 的 名 字 。 


- milestone: 标记 该 插件 的 开发 里 程 碑 ， 一 般 为 1，2，3。 如 果 不 再 维护 的 ， 标 记 为 0。 


- config: 可 以 定义 很 多 个 ， 即 该 插件 在 Logstash 配 置 文件 中 的 可 配置 参数 。Logstash 很 温 声 的 提供 了 验证 方法 ， 确 保 接 收 的 数据 是 你 期 望 的 数据 类 型 。 


- register: Logstash 在 启动 的 时 候 运行 的 函数 ， 一 些 需要 常 驻 内 存 的 数据 ， 可 以 在 这 一 步 先 完成 。 比 如 对 象 初 始 化 ，logstash-filter-ruby 插 件 中 的 init 语 名 等。 


milestone 级 别 在 3 以 下 的 ，Logstash 默 认为 不 足够 稳定 ， 会 在 启动 阶段 ， 读 取 到 该 插件 的 时 候 ， 输 出 类 似 下 面 这 样 的 一 行 提示 信息 ， 日 志 级 别 是 warn。 这 不 代表 运行 出 错 ! 只 是 提示 如 果 用 户 碰 到 
bug， 欢 迎 提供 线索 。 


{:timestamp=>“2015-02-06T10:37:26.312000+0800”，:message=>“Using milestone 2 
input plugin 'file'. This plugin should be stable, but if you see strange 
behavior, please let us know! For more information on plugin milestones, see 
http://logstash.net/docs/1.4.2-modified/plugin-milestones , :level-»:warn] 


7.2 ”插件 的 关键 方法 


上 节 示 例 中 ， 输 入 插件 独 有 的 是 run 方 法 。 在 run 方 法 中 ， 必 须 实现 一 个 长 期 运行 的 程序 (最 简单 的 就 是 loop 指 令 ) 。 然 后 在 每 次 收 到 数据 并 处 理 成 event 之 后 ， 一 定 要 调用 queue< <event 语 句 。 一 个 
输入 流程 就 算是 完成 了 。 


而 如 果 是 过 滤器 插件 ， 对 应 修改 成 : 


require 'logstash/filters/base' 

class LogStash::Filters::MyPlugin « LogStash::Filters::Base 
public def filter (event) 
end 

end 


输出 插件 则 是 : 


require 'logstash/outputs/base' 

class LogStash::Outputs::MyPlugin < LogStash: :Outputs::Base 
public def receive (event) 
end 

end 


另外 ， 为 了 在 终止 进程 的 时 候 不 遗失 数据 ， 建 议 都 实现 如 下 这 个 方法 ， 只 要 实现 了 ，Logstash 在 shutdown 的 时 候 就 会 自动 调 


public def teardown 
end 


推荐 阅读 


《Extending logstash? http:/ /logstash.net/docs/1.4.2/extending/ 


* «Plugin Milestones? http://logstash.net/docs/1.4.2/plugin-milestones 


73 插件 打包 


Logstash 从 1.5.0-GA 版 开始 ， 对 插件 规范 做 了 重大 变更 。 放 弃 了 milestone 定 义 ， 去 除了 --pluginpath 命 令 行 参数 。 统 一 改 成 bin/plugin 管 理 的 rubygem 包 插件 。 那 么 ， 我 们 自己 写 的 Logstash 插 件 ， 
也 同样 需要 适应 这 个 新 规则 ， 写 完 Ruby 代 码 ， 还 要 打包 成 gem 才 能 使 用 。 


为 了 我 们 更 方便 的 完成 工作 ，Logstash 针 对 4 种 插件 形态 提供 了 4 个 示例 库 ， 可 以 按照 自己 所 需 克 隆 使 用 。 比 如 要 写 一 个 logstash-filter-mything 揪 件 : 


git clone https://github.com/logstash-plugins/logstash-filter-example 
cd logstash-filter-example 

mv logstash-filter-example.gemspec logstash-filter-mything.gemspec 
mv lib/logstash/filters/example.rb lib/logstash/filters/mything.rb 

mv spec/filters/example spec.rb spec/filters/mything spec.rb 


dE dbdEGEGE 


然后 把 代码 写 在 lib/logstashyfilters/mything.rb 里 即 可 。 


代码 部 分 完成 。 然 后 就 是 定义 gem 打 包 需 要 的 额外 文件 和 库 依赖 了 。 目 录 中 有 两 个 文件 Gemfile 和 logstash-filter-mything.gemspec。 


Gemfile 文 件 就 是 标准 格式 ， 用 来 运行 bundler install 时 下 载 rubygems 包 的 。 默 认 情 况 下 ， 最 基础 的 内 容 是 : 


source 'https://rubygems.org' 4 国内 建议 改 成 'http://ruby.taobao.org' 
gemspec 
gem "logstash' , :github => "elastic/logstash' , :branch => “1.5” 


gemspec 文 件 则 是 用 来 定义 软件 包 本 身 规范 ， 不 单 限 于 rubygems。 示 例如 下 : 


Gem::Specification.new do |s| 
s.name = 'logstash-filter-mything' 
s.version = '1.1.0' 
s.licenses = ['Apache License (2.0) *] 
s.summary = “This mything filter is just for ELKstack Guide example" 
s.description = "This gem is a logstash plugin required to be installed on 
top of the Logstash core pipeline using $LS HOME/bin/plugin install gemname. 
This gem is not a stand-alone program" 
.authors = [ "Chenryn' ] 
.email = 'chenlin78staff.sina.com.cn' 
.homepage = "http://kibana.logstash.es" 
.require paths = [ “lib” ] 
.files = 'find . -type f ! -wholename '*.svn*''.split ($V) 
.test files = s.files.grep ($r(^ (test|spec|features) /]) 
.metadata = ( “logstash plugin" => “true” , “logstash group” => "filter" } 
.add runtime dependency “logstash-core” , '»- 1.4.0', '« 2.0.0" 
.add development dependency 'logstash-devutils' 


&.u0 uo uououoututu 


o 
5 


其 中 : 


'Ss.Vetsion 就 是 milestone 的 替代 品 ，0.1.x 相 当 于 是 milestone 0; 0.9.x 相 当 于 是 milestone 2; 1.x.x 相 当 于 是 milestone 3。 


t sfile 默 认 写 法 是 gitls-files， 因 为 默认 是 git 库 ， 如 果 你 本 身 采 用 了 svn， 或 者 cvs 库 ， 都 不 要 紧 ， 只 要 命令 列 出 的 是 你 需要 打包 进去 的 文件 即 可 。 


- s.metadata 是 Logstash 的 plugin 命 令 在 install 的 时 候 会 提前 vetify 的 特殊 信息 ， 一 定 要 保留 。 


好 了 ， 全 部 完毕 。 下 面 打包 : 


# gem build logstash-filter-mything.gemspec 


运行 完 就 会 生成 一 个 logstash-filter-mything-1.1.0.gem 软 件 包 ， 可 以 安装 使 


74 Filter 揪 件 开发 示例 


前 几 节 详解 了 插件 开发 中 的 一 些 细节 ， 却 有 “如 七 宝 楼 台 ， 眩 人 眼目 ， 碎 拆 下 来 ， 不 成 片段 ”的 感觉 。 下 面 ， 我 们 实际 开发 一 个 自己 的 Logstash 过 滤 插件 。 


官方 插件 中 ， 有 一 个 叫 logstash-filter-geoip， 也 算是 很 常用 的 一 个 功能 。 不 过 GeolP 库 在 国内 IP 归 属 上 ， 准 确 率 不 到 70%。 此 外 ，GeolP 库 在 格式 上 也 有 缺陷 : 第 一 读 取 性 能 不 够 ， 第 二 无 法 | 


自 定义 数 


据 。 所 以 ，MaxMind 公 司 也 推出 了 新 一 代 的 MaxMindDB 格 式 以 及 对 应 的 GeoLite2.mmdb 免 费 IP 地 址 库 。mmdb 格 式 是 公开 的 ， 可 以 自己 生成 自己 的 IP 数 据 库 ， 同 时 读 取 性 能 比 原 GeolP 高 4~ 6 倍 。 
mmdb 格 式 说 明文 档 见 下 面 链接 : https;//github.com/maxmind/MaxMind-DB/blob/master/MaxMind-DB-spec.md 


744 mmdb 数 据 库 的 生成 方法 


MaxMind 官 方 只 提供 了 Perl 版 本 的 mmdb 写 入 库 。 通 过 下 面 命令 安装 : 


# cpanm MaxMind: :DB: :Writer 


假设 你 有 一 个 ipdata.csv 文 件 ， 每 行 记录 的 是 一 个 IP 段 的 开始 IP， 结 束 IP， 归 


use MaxMind::DB: :Writer::Tree; 
use Net: :Works: :Network; 
my $tree = MaxMind::DB::Writer::Tree-»new ( 


ip version => 4, 
record size => 24, 
database type => 'MMDB', 
description => { 


en => 'My MaxMindDB', 
h 
map key type callback => sub ( 'utf8 string' ),) ; 
open my $rfh, “<” , "ipdata.csv' ; 
while («$rfh») { 
chomp; 


Fb 


国家 、 省 、 市 、 街 道 、 运 营 商 、 其 他 注释 。 那 么 生成 mmdb 文 件 的 示例 程序 如 下 : 


my ( $start ip, $end ip, $country, $province, $city, $district, $isp, $desc 


) = split /N/, $ ; 


my Gsubnets = Net::Works::Network-»range as subnets ($start ip, $end ip) ; 


for my $subnet (G8subnets) { 
Stree-»insert network ($subnet, ( 
country => Scountry, 
province => $province, 
city => $city, 
district => $district, 
isp => $isp, 
desc => $desc, 
D; 
} 
} 
open my $fh, '>', “ipdata.mmdb” ; 
$tree->write_tree ($fh) ; 


7.4.2 LogStash: : Filters: : Mmdb 实 现 


1.mmdb 数 据 库 的 Java 客 户 端 


考虑 到 Logstash 是 JRuby 实 现 ， 而 这 种 计算 型 的 需求 ， 纯 Ruby 实 现 肯定 比 不 过 Java。 所 以 我 们 需要 把 IP 地 址 解析 这 段 逻辑 


W: https;//github.com/maxmind/MaxMind-DB-Reader-java, 
Ors 
实测 证 明 ，JRuby 上 使 用 纯 Ruby 实 现 的 mmdb 库 性 能 比 Java 库 差 两 个 数量 级 。 


读 取 mmdb 文 件 进行 IP 地 址 解析 的 Java 代 码 示例 如 下 : 


import java.io.File; 

import java.net.InetAddress; 

import com.fasterxml.jackson.databind.JsonNode; 

import com.maxmind.db.Reader; 

import com.maxmind.db.Reader.FileMode; 

File database = new File ( "/path/to/database/GeoIP2-City.mmdb" ) ; 
Reader reader - new Reader (database, FileMode.MEMORY MAPPED) ; 
InetAddress address = InetAddress.getByName ( “24.24.24.24” ) ; 
JsonNode response = reader.get (address) ; 

System.out.println (response) ; 

reader.close () ; 


Java 搞 定 。MaxMind 官 方 提供 Java 版 本 的 mmdb 文 件 读 取 库 ， 源 代码 地 址 


2. 在 Logstash 插 件 中 实现 的 源码 解析 


把 上 面 的 Java 代 码 迁 移 到 Logstash 里 ， 最 后 实际 实现 是 这 个 样子 : 


# encoding: utf-8 
require "logstash/filters/base" 
require "logstash/namespace" 


require "logstash/environment" 

require "logstash-filter-mmdb jars.rb" 

class LogStash::Filters::MMDB < LogStash::Filters::Base 
config name “mmdb” 
config :database, :validate => :path 
config :source, :validate => :string, :required => true 
config :fields, :validate => :array 
config :target, :validate => :String :default => 'geoip' 


public 
def register 
require “java” 


import com.maxmind.db.Reader 
import java.net.InetAddress 
if G8database.nil? 
Gdatabase = ::Dir.glob (: : File.join (: : File.expand path ( '"///vendor/" , 
:iFile.dirname ( FILE ) ) , "GeoLite2-City.mmdb' ) ) . first 
if !File.exists? (8database) 
raise “You must specify 'database => … 
'd(Gdatabase)' " 


in your mmdb filter (I looked for 


end 
end 
Glogger.info ( "Using mmdb database” , :path => (database) 
db = java.io.File.new (8database) 
(reader = Reader.new (db) 
end 
public 
def filter (event) 
return unless filter? (event) 
begin 
ip = event [source] 
ip = ip.first if ip.is a? Array 
data = 8reader.get (NetAddress.getByName (ip) ) 
event[Gtarget] = () if event[Gtarget].nil? 
if Gfields.empty? 
event [Gtarget].merge! (LogStash::Json.load (data.toString) ) 
else 
Gfields.each do |f| 
event [@target] [f] = data.get (f) 
end 
end 
end 
filter matched (event) 
end E 
end 


74.3 logstash-filter-mmdb 打 包 


打包 使 用 的 gemspec 和 上 一 节 示例 几乎 一 致 ， 需 要 注意 的 是 jar 包 依赖 。 从 Logstash 1.5.1 版 本 开始 ， 官 方 建议 插件 作者 们 通过 直接 分 发 jar 包 的 方式 完成 ， 并 提供 了 统一 的 运行 时 加 载 接口 。 具 体 的 说 ， 


我 们 需要 创建 vendor/jar-dependencies/runtime-jars 目 录 ， 把 我 们 下 载 的 jar 包 ， 包 括 深层 依赖 的 其 他 jar 包 ， 都 放 进去 。 完 成 logstash-filter-mmdb 揪 件 ， 最 终 的 目录 文件 如 下 : 


# ls vendor/jar-dependencies/runtime-jars/commons-codec-1.3.jar commons-logging- 
1.1.1.jar jackson-annotations-2.4.0.jar jackson-core-2.4.3.jar jackson-databind 
-2.4.3.jar jsr305-1.3.9.jar maxmind-db-1.0.0.jar 


然后 ， 还 需要 创建 另 一 个 运行 时 依赖 接口 文件 lib/logstash-filter-mmdb jars.rb， 内 容 如 下 : 


# encoding: utf-8 

require 'logstash/environment' 

ROOT DIR = File.expand path (File.join (File.dirname ( FILE ) , “”)) 
LogStash::Environment.load runtime jars! File.join (ROOT DIR, "vendor" ) 


打包 logstash-filter-mmdb 的 难点 不 止 一 个 ， 我 们 还 有 一 个 GeoLite2-City.mmdb 的 IP 地 址 库 文件 。 也 需要 跟 插 件 一 起 分 发 。 所 以 还 需要 多 加 一 个 vendorjson 文 件 ， 来 定义 分 发 文件 的 下 载 地 址 。 格 式 


如 下 : 


[{ “url” : "http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb. 
gz” , “shal” : “ 3835c98c6444365cd3b3a7769f13e2c9aba6a36d”}] 


多 个 文件 的 话 ， 数 组 里 同样 格式 写 多 个 元 素 即 可 。 这 样 在 打包 的 时 候 ， 先 运行 rake vendor 命 令 ， 就 会 自动 下 载 文件 供 后 续 使 用 了 。 
Qua 


如 果 有 商用 场景 ， 请 不 要 直接 分 发 GeoLite2 地 址 库 。MaxMind 对 此 的 发 布 协议 是 有 一 年 期 限制 的 。 这 也 是 Logstash 官 方 本 身 不 写 这 个 插件 的 原因 。 


7.5 Input 插件 开发 示例 


我 们 知道 Linux 系 统 有 些 重要 日 志 不 是 以 可 读 文本 形式 存在 文件 中 ， 而 是 以 二 进 制 内 容 存 放 的 。 比 如 utmp、wtmp、lastlog 等 。 


logstash-input-file 插 件 在 读 取 二 进 制 文 件 和 文本 文件 时 的 区 别 ， 在 于 二 进 制 文 件 没 办 法 一 行 行 处 理 内容 ， 内 容 也 不 是 直观 可 见 的 。 除 此 以 外 ， 其 他 处 理 逻 辑 是 保持 一 致 的 ， 比 如 多 文件 支持 、 断 点 续 


传 、 内 容 监 控 等 。 所 以 ， 我 们 可 以 借鉴 logstash-input-file 的 实现 方式 ， 完 成 自己 的 logstash-input-utmp 插 件 ， 实 现 对 二 进 制 文件 的 读 取 和 解析 ， 得 到 逐 行 输出 的 文本 内 容 ， 供 后 续 filter 阶 段 使 


7.5.1 ”FileWatch 模 块 原理 


Logstash-input-file 揪 件 使 用 了 FileWatch 模 块 的 Tail 类 来 完成 对 文本 文件 的 读 取 。 仔 细 阅 读 这 个 类 的 源码 实现 ， 发 现 其 中 最 关键 的 几 行 代码 就 是 在 _read _file 方 法 中 : 


loop do 
begin 
data = @files[path] .sysread (32768) 
changed = true 
Gbuffers[path].extract (data) . each do |line| 
yield (path, line) 


Gsincedb[Gstatcache[path]] += (line.bytesize + delimiter byte size) 
end 
rescue Errno::EWOULDBLOCK, Errno::EINTR, EOFError 
break 
end 
end 


在 这 个 方法 中 ，FileWatch: : Tail 固 定 每 次 读 入 32768 字 节 的 数据 ， 然 后 根据 分 隔 符 (默认 就 是 \n) 转换 成 一 行 行 发 送出 去 ， 同 时 更 新 sincedb 里 的 数据 。 


所 以 ,我 们 只 需要 自己 实现 针对 二 进 制 文件 的 读 取 长 度 定义 和 内 容 转 换 方 法 即 可 。 下 面 是 具体 实现 ， 我 们 可 以 放 在 我 们 可 以 放 在 logstash-input-utmp/lib/logstash/inputs/binarytail.rb 中 : 


# encoding: utf-8 

require "filewatch/helper" 

require "filewatch/buftok" 

require "filewatch/watch" 

require "filewatch/tail" 

class FixBlockTail « FileWatch::Tail 

def setblocksize (blocksize) 

Gblocksize = blocksize 


end 
private 
def read file (path, &block) 
Gbuffers[path] ||= FileWatch::BufferedTokenizer.new (Gopts[:delimiter]) 
changed - false 
loop do 
begin 


data = Gfiles[path].sysread (Gblocksize) 
changed - true 
yield (path, data) 
Gsincedb[8statcache[path]] += G8blocksize 
rescue Errno::EWOULDBLOCK, Errno::EINTR, EOFError 
break 
end 
end 
if changed 
now = Time.now.to i 
delta = now - 8sincedb last write 
if delta >= Gopts[:sincedb write | interval] 
Glogger. debug? && i opge: debug ( “writing sincedb (delta since last write 
#{delta}) 
sincedb write 
Gsincedb last write = now 
end 
end 
end # def read file 
end 


在 类 声明 时 ， 通 过 继承 原 有 的 FileWatch: : Tail 类 ， 我 们 的 新 实现 中 ， 只 需要 修改 read file 方 法 ， 其 他 的 都 不 用 重新 写 了 。 


7.5.2 LogStash: : Inputs: : Utmp 实 现 


前 面 讲 到 ， 对 二 进 制 文件 ， 最 重要 的 是 读 取 长 度 和 解析 方法 。 对 utmp 文 件 的 二 进 制 结构 ， 我 们 可 以 通过 man utmp 命 令 查看 结构 体 的 类 型 。 在 动态 语言 中 ， 要 解析 二 进 制 结构 体 的 内 容 ， 通 常 要 使 
pack/unpack 指 令 。 比 如 ，utmp 文 件 对 应 的 unpack 指 令 是 : 


s21a32a4a32a256s21i1214a20 


比如 其 中 第 一 位 是 s 代 表 short， 后 面 的 数字 2 代表 short 元 素 的 个 数 ， 也 就 是 结构 体 的 第 一 个 和 第 二 个 元 素 是 short 类 型 ， 各 占 连 个 两 个 字 节 。 


以 此 类 推 。s21a32a4a32a256s2il214a20 总 共 代表 384 个 字 节 ， 与 struct_size 配 置 保持 一 致 。 其 余 T、a、i 乃 至 更 多 指令 含义 参见 Ruby 官 方 的 pack 函 数 说 明 ，http://ruby-doc.org/core- 
1.9.3/Array.html#method-i-pack。 


注意 的 是 ， 你 必须 了 解 你 的 操作 系统 的 字 节 序 是 大 端 模式 还 是 小 端 模式 ， 这 对 于 数字 类 型 的 结构 体 元 素 很 有 必要 ， 比 如 对 于 i 和 | 的 选择 。 另 一 个 影响 是 结构 体内 存 对 齐 的 问题 ， 实 际 上 utmp 结 构 体 
第 一 个 元 素 是 2 字 节 ， 第 二 个 元 素 是 4 字 节 。 编 译 器 在 编译 的 时 候 会 在 第 一 个 2 字 节 后 插入 2 字 节 来 补 齐 到 4 字 节 ， 知 道 这 点 尤为 重要 。 所 以 其 实 第 二 个 short 是 无 意义 的 ， 只 是 为 了 内 存 对 齐 才 补 的 。 


好 了 ， 现 在 两 个 数据 都 拿 到 了 ， 读 取 长 度 384 字 节 ， 解 析 方式 采用 对 应 的 unpack 指 令 。 为 了 更 加 通用 一 些 ， 比 如 在 Linux 平 台 和 OSX 平 台 上 ，utmp 结 构 体 定义 就 不 一 致 ， 我 们 把 这 两 个 数据 抽象 成 配置 
参数 struct_size 和 struct_format。 最 终 的 LogStash: : Inputs: : Utmp 实 现 如 下 : 


# encoding: utf-8 
require “logstash/inputs/base” 
require “logstash/namespace” 
require “pathname” 
require “socket” # for Socket.gethostname 
require relative "binarytail" 
class LogStash: iInputs::Utmp < LogStash: : Inputs: :Base 
config_name "utmp" 
default :codec, "plain" 
config :path, :validate => :array, :required => true 
config :exclude, :validate :array 
config :stat interval, :validate => :number, :default => 1 
config :discover interval, :validate => :number, :default => 15 
config :sincedb path, :validate => :string 
config :sincedb write interval, :validate => :number, :default => 15 
config :start position, :validate => [ “beginning” , “end” ], :default => "end" 
config :delimiter, :validate => :string, :default => “” 
config :struct size, :validate => :number, :default -» 384 
config :struct format, :validate => :string, :default => "s21a32a4a32a256s2i1214a20" 
public 7 
def register 
require “addressable/uri” 
require “filewatch/tail” 
require “digest/md5” 
@logger.info ( "Registering utmp input” , :path => @path) 
Ghost = Socket.gethostname.force encoding (Encoding::UTF 8) 
Gtail config = ( 
:exclude => Gexclude, 
:stat interval => 8stat interval, 
:discover interval -» (discover interval, 
:sincedb write interval => 8sincedb write interval, 
:delimiter => Gdelimiter, 
:logger => Glogger, 


sincedb dir = ENV[ "SINCEDB DIR” ] || ENV[ "HOME" ] 
8sincedb path = File. dps (sincedb dir, ".sincedb " + Digest::MD5.hexdigest (8 
path.join ( *," ) ) ) 


old sincedb - File. join (sincedb dir, ^".sincedb" ) 
if File.exists? (old sincedb) 
File.rename (old sincedb, Gsincedb path) 
end 
end 
Gtail config[: sincedb path] — Gsincedb path 
if 8start position == "beginning" 
8tail config[:start new files at] = :beginning 
end 
end 4 def register 
public 
def run (queue) 
Gtail = FixBlockTail.new (8tail config) 
Gtail.setblocksize (8struct size) 
Gpath.each ( |path| 8tail.tail (path) } 
Gtail.subscribe do |path, line| 
event = ,LogStash: :Event.new 


event[ "[6metadata][path]" ] = path 
event[ “host” ] = @host if !event.include? ( “host” ) 
event[ “path” ] = path if !event.include? ( “path” ) 


struct = line.unpack (@struct_format) ; 
event [ “message” ] = struct.join ( “I” ) 
decorate (event) 
queue << event 

end 

finished 


end 4 def run 
public 
def teardown 
if Gtail 
Gtail.sincedb write 
Gtail.quit 
Gtail = nil 
end 
end 4 def teardown 
end # class LogStash: : Inputs: :Utmp 


代码 中 省 略 了 与 主体 功能 无 关 的 部 分 变量 判断 和 调试 日 志 记录 逻辑 ， 


有 实 上 ，register 方 法 完全 等 同 于 logstash-input-file 插 件 的 实现 ， 读 者 可 以 拿 官方 实现 作为 对 比 。 


代码 中 ， 采 用 了 require_relative 指 令 加 载 在 上 一 小 节 我 们 创建 的 binarytail.rb 库 文件 ， 该 指令 与 普通 require 指 令 的 区 别 在 于 : 它 是 在 本 身 所 在 路 径 下 查找 和 加 载 。 


然后 在 run 方 法 中 ， 不 再 使 用 FileWatch: : Tail 类 ， 而 是 我 们 自己 实现 的 FixBlockTail 类 ， 并 加 载 @struct_size 数 据 长 度 参 数 。 


最 后 ， 在 LogStash: : Event 生 成 方面 ， 可 以 看 到 跟 6.2.1 节 内 容 不 太一 样 的 是 ， 一 般 的 Input 插 件 都 会 在 这 时 候 调用 @codec.decode () 方法 来 将 数据 转换 成 对 象 ， 不 过 对 我 们 现在 要 解析 的 utmp 来 
说 ,没有 必要 为 了 一 行 unpack 指 令 ， 再 单独 开发 一 个 logstash-codec-unpack 揪 件 来 共同 完成 一 件 事情 了 。 所 以 ， 这 里 直接 把 codec 的 任务 一 并 完成 ， 直 接 初 始 化 一 个 LogStash: : Event 对 象 ， 将 
unpack 得 到 的 文本 数据 赋值 给 event["message"] 字 段 。 


所 以 ， 这 个 示例 其 实 是 一 个 融合 了 Input 和 Coded 插 件 的 实现 ， 也 算是 对 第 6 章 原理 阐述 的 实例 展现 。 读 者 可 以 根据 自己 的 实际 场景 需求 ， 来 决定 自己 是 否 单独 拆 分 codec 功 能 到 额外 的 插件 里 。 


7.6 ”Output 揪 件 开发 示例 


consu| 是 一 个 GOSSIP 协 议 的 分 布 式 服务 发 现 和 配置 中 心软 件 。 和 ZooKeeper、etcd 相 比 还 多 了 健康 检查 和 DNS 协议 接口 等 对 运 维 工程 师 非 常 友好 的 功能 ， 所 以 在 微服 务 和 容器 化 浪潮 中 ，consul 成 为 
Docker 生 态 圈 中 最 重要 的 一 环 。 


本 节 以 consul 的 key-value 存 储 为 例 ， 演 示 Logstash 的 Output 揪 件 开 发 。 对 于 Logstash 二 次 开发 而 言 ，Output 揪 件 是 最 简单 的 ， 几 乎 不 再 涉及 Logstash 本 身 的 设计 和 规范 ， 所 以 目前 Logstash 社 区 
中 ，Output 插 件 的 数量 也 是 最 多 的 。 


下 面 是 logstash-output-consul 插 件 的 代码 实现 : 


require "logstash/namespace" 
require "logstash/outputs/base" 
require "logstash/plugin mixins/http client" 
require "manticore" 
class LogStash::Outputs::Consul < LogStash::Outputs::Base 
include LogStash::PluginMixins::HttpClient 
config name "consul" 
config :consul ip, :validate => :string, :required => true 
config :consul port, :validate => :number, :required => false, :default => 8500 
config :path, :validate => :string, :required => true 
config :value field, :validate => :string, :required => true 
config :flags, :validate -» :string, :required => false 
public 
def register 
Gurlpath = "http://f(8consul ip):f(6consul port)/vl/kv/" 
end 
public 
def receive (event) 
return unless output? (event) 
Gurlpath += event.sprintf (epath) 
if Gflags.size > 1 do 
Qurlpath += “?flags=” *event.sprintf (8flags) 


end 
client.put (G(urlpath, body: event.sprintf (Gvalue field) ) 
end 
end 


在 这 段 代 码 中 ， 有 两 处 需要 注意 的 


法 ， 下 面 分 别 讲解 。 


1.event.sprintf () 函数 


我 们 在 Logstash 配 置 中 使 用 的 那些 字段 引用 字符 串 ， 最 常见 的 就 是 logstash-output-elasticsearch 里 的 index_name 和 和 filter 插 件 的 add _field， 都 是 通过 这 个 函数 生成 的 结果 。 在 本 例 中 ， 假 设 配置 如 


output { 
consul { 
consul ip => “192.168.0.2” 
path => “/[upstream addr]/ [status] 
value field => “requesttime” 
} 
} 


那么 对 下 面 这 条 日 志 : 


( "Gtimestamp' : "2015-08-20T17:19:20Z" , "upstream addr” : "192.168.0.3" , "requesttime" 
:0.32, “status” :200, "urlpath' : "/index.html" ) 


最 终 就 会 生成 一 个 下 面 这 样 的 请 求 : 


* curl -XPUT http://192.168.0.2:8500/v1/kv/192.168.0.3/200 -d “0.32” 


当然 ， 实 际 上 不 太 可 能 会 有 需求 把 每 条 日 志 的 响应 时 间 更 新 一 次 Consul。 所 以 ， 该 插件 更 适合 的 场景 是 配合 logstash-filter-metrics 插 件 ， 将 metric 统 计 值 写 入 consul。 


2.logstashVplugin_mixins/http_client 插 件 


这 个 插件 从 路 径 名 里 就 可 以 看 出 来 ， 并 不 是 传统 意义 上 的 数据 处 理 流程 中 的 插件 。 确 切 地 说 ， 这 是 Logstash 开 发 组 为 了 解决 社区 插件 开发 中 ， 滥 用 不 同 HTTP 基 础 库 的 问题 ， 特 意 整理 出 来 的 功能 
件 。 其 底层 采用 了 和 logstash-output-elasticsearch 相 同 的 manticore 库 ， 并 封装 好 了 和 Proxy、SSL 等 高 级 功能 相关 的 config 配 置 。 目 前 ， 官 方 的 logstash-input-http_poller 就 采用 了 这 个 插件 。 


include LogStash::PluginMixins::HttpClient 


这 么 一 行 代码 ， 这 个 插件 就 给 你 的 代码 自动 导出 了 client 对 象 ， 并 且 提供 一 系列 和 HttpClient 相 关 的 可 配置 项 。 具 体 参数 见 : 


https: //github.com/logstash-plugins/logstash-mixin-http client 


目前 ，Logstash 只 有 两 个 功能 插件 ， 另 一 个 是 logstash-mixin-awsconfig， 如 果 你 打算 开发 一 个 跟 AWS 云 平台 相关 的 插件 ， 可 以 加 载 这 个 功能 插件 ， 自 动 提供 一 系列 和 AWS 相 关 的 可 配置 项 。 


第 二 部 分 Elasticsearch 


“第 8 章 ”架构 原理 

: 第 9 章 ”数据 接口 用 例 

“ 第 10 章 ”性 能 优化 

“第 11 章 测试 和 扩展 方案 

“ 第 12 章 ”映射 与 模板 的 定制 

:第 13 章 ”监控 方案 

“ 第 14 章 “Elasticsearch 在 运 维 监控 领域 的 其 他 应 用 


Elasticsearch 来 源 于 作者 Shay Banon 的 第 一 个 开源 项 目 Compass 库 ， 而 这 个 Java 库 最 初 的 目的 只 是 为 了 给 Shay 当时 正在 学 厨师 的 妻子 做 一 个 菜谱 的 搜索 引擎 。2010 年 ，Elasticsearch 正 式 发 布 ， 至 今 已 经 成 为 
GitHub 上 最 流行 的 Java 项 目 ， 不 过 Shay 承 诺 给 妻子 的 菜谱 搜索 依然 没有 面世 …… 


2015 年 年 初 ，Elasticsearch 公 司 召 开 了 第 一 次 全 球 用 户 大 会 Elastic{ON}15。 诸 多 I 芽 巨 头 纷纷 赞助 、 参 会 、 演 讲 。 会 后 ，Elasticsearch 公 司 宣布 改名 Elastic， 公 司 官网 也 变 成 http://elastic.co/ 。 这 意味 着 
Elasticsearch 的 发 展 方向 不 再 限于 搜索 业务 ， 也 就 是 说 ，ELK stack 等 机 器 数据 和 IT 服务 领域 成 为 官方 更 加 注意 的 方向 。 随 后 几 个 月 ， 专 注 监控 报警 的 Watcher 发 布 beta 版 ， 社 区 有 名 的 网 络 抓 包 工具 Packetbeat 也 
被 Elastic 公 司 收 购 。 


第 8 章 ”架构 原理 


Elasticsearch 的 一 些 架构 设计 ， 对 我 们 做 性 能 调 优 、 故 障 处理 ， 具 有 非常 重要 的 影响 。 所 以 ， 作 为 Elasticsearch 部 分 的 起 始 章节 ， 先 从 数据 流向 和 分 布 的 层面 ， 介 绍 一 下 Elasticsearch 的 工作 原理 ， 以 
及 相关 的 可 控 项 。 对 基础 内 容 熟 悉 的 读者 可 以 跳 过 这 章 先 阅读 后 面 的 运 维 操作 部 分 ， 但 作为 性 能 调 优 的 基础 知识 ， 依 然 建议 大 家 抽 时 间 返 回来 了 解 。 


本 书 作为 ELK stack 指 南 ， 关 注 于 Elasticsearch 在 日 志和 数据 分 析 场 景 的 应 用 ， 并 不 打算 对 底层 的 Lucene 原 理 或 者 java 编程 做 详细 的 介绍 ， 本 章 主 要 内 容 包 括 : 准 实时 索引 的 实现 ，segment merge 的 
影响 ，routing 和 replica 的 读 写 过 程 ，shard 的 allocate 控 制 ， 自 动 发 现 的 配置 。 


8.1“ 准 实时 索引 的 实现 


既然 介绍 数据 流向 ， 首 先 第 一 步 就 是 : 写 入 的 数据 是 如 何 变 成 Elasticsearch 里 可 以 被 检索 和 聚合 的 索引 内 容 的 。 


以 单 文件 的 静态 层面 看 ， 每 个 全 文 索引 都 是 一 个 词 元 的 倒 排 索引 ， 具 体 涉及 全 文 索引 的 通用 知识 ， 这 里 不 单独 介绍 ， 有 兴趣 的 读者 可 以 阅读 《Lucene in Action》 等 书籍 详细 了 解 。 本 节 介绍 数据 在 写 
入 Elasticsearch 索 引流 程 中 发 生 的 具体 操作 。 重 点 在 于 其 中 segment、buffer 和 translog 三 部 分 对 实时 性 和 性 能 方面 的 影响 。 


843.1 动态 更 新 的 Lucene 索 引 


以 在 线 动 态 服务 的 层面 看 ， 要 做 到 实时 更 新 条 件 下 数据 的 可 用 和 可 靠 ， 就 需要 在 倒 排 索 引 的 基础 上 ， 再 做 一 系列 更 高 级 的 处 理 。 


其 实 总结 一 下 Lucene 的 处 理 办 法 ， 很 简单 ， 就 是 一 句 话 : 新 收 到 的 数据 写 到 新 的 索引 文件 里 。 
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图 8-1 写 入 前 索引 状态 


Lucene 把 每 次 生成 的 倒 排 索引 ， 叫 做 一 个 段 (segment) 。 然 后 另外 使 用 一 个 commit 文 件 ， 记 录 索 引 内 所 有 的 segment。 而 生成 sgment 的 数据 来 源 ， 则 是 内 存 中 的 buffer。 也 就 是 说 ， 动 态 更 新 过 
程 如 下 : 


1) 当前 索引 有 3 个 segment 可 用 。 索 引 状 态 如 图 8-1 所 示 。 


2) 新 接收 的 数据 进入 内 存 buffer。 索 引 状 态 如 图 8-2 所 示 。 


3) 内 存 buffer 刷 到 磁盘 ， 生 成 一 个 新 的 segment，commit 文 件 同步 更 新 。 索 引 状 态 如 图 8-3 所 示 。 
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8.1.2 ”利用 磁盘 缓存 实现 的 准 实时 检索 


既然 涉及 磁盘 ， 那 么 一 个 不 可 避免 的 问题 就 来 了 : 磁盘 太 慢 了 ! 对 我 们 要 求实 时 性 很 高 的 服务 来 说 ， 这 种 处 理 还 不 够 。 所 以 ， 在 第 3 步 的 处 理 中 ， 还 有 一 个 中 间 状 态 : 


1) 内 存 buffer 生 成 一 个 新 的 segment， 刷 到 文件 系统 缓存 中 ，Lucene 即 可 检索 这 个 新 segment。 索 引 状 态 如 图 8-4 所 示 。 
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2) 文件 系统 缓存 真正 同步 到 磁盘 上 ，commit 文 件 更 新 。 达 到 图 8-3 中 的 状态 。 


这 一 步 刷 到 文件 系统 缓存 的 步骤 ， 在 Elasticsearch 中 ， 是 默认 设置 为 1 秒 间隔 的 ， 对 于 大 多 数 应 用 来 阅 ， 几 乎 就 相当 于 是 实时 可 搜索 了 。Elasticsearch 也 提供 了 单独 的 /_refresh 接 口 ， 用 户 如 果 对 1 秒 间 
隔 还 不 满意 的 ， 可 以 主动 调用 该 接口 来 保证 搜索 可 见 。 


不 过 对 于 ELK stack 的 日 志 场景 来 说， 恰恰 相反 ， 我 们 并 不 需要 如 此 高 的 实时 性 ， 而 是 需要 更 快 的 写 入 性 能 。 所 以 ， 一 般 来 说 ， 我 们 反而 会 通过 /_settings 接 口 或 者 定制 template 的 方式 ， 加 大 
refresh_interval 参 数 : 


4 curl -XPOST http://127.0.0.1:9200/10gstash-2015.06.21/ settings -d' 
{ “refresh interval” : “10s” } 
' 


如 果 是 导入 历史 数据 的 场合 ， 那 甚至 可 以 先 完全 关闭 掉 : 


# curl -XPUT http://127.0.0.1:9200/logstash-2015.05.01 -d' 
{ "settings" : { 'refresh interval' : ^"-1" 


p 


在 导入 完成 以 后 ， 修 改 回来 或 者 手动 调用 一 次 即 可 : 


# curl -XPOST http://127.0.0.1:9200/10gstash-2015.05.01/ refresh 


8.1.3 translog 提 供 的 磁盘 同步 控制 


既然 refresh 只 是 写 到 文件 系统 缓存 ， 那 么 最 后 一 步 写 到 实际 磁盘 又 是 由 什么 来 控制 的 ? 如 果 这 期 间 发 生 主机 错误 、 硬 件 故障 等 异常 情况 ， 数 据 会 不 会 丢失 ? 


这 里 ， 其 实 有 另 一 个 机 制 来 控制 。Elasticsearch 在 把 数据 写 入 到 内 存 buffer 的 同时 ， 其 实 还 另外 记录 了 一 个 translog 日 志 。 也 就 是 说 ， 第 2 步 也 并 不 是 图 8-2 的 状态 ， 而 是 像 图 8-5 这 样 。 


在 第 3 和 第 4 步 ，refresh 发 生 的 时 候 ，translog 日 志文 件 依然 保持 原样 ， 如 图 8-6 所 示 。 
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图 8-6 ”translog 继 续 记 录 
也 就 是 说 ， 如 果 在 这 期 间 发 生 异常 ，Elasticsearch 会 从 commit 位 置 开 始 ， 恢 复 整 个 translog 文 件 中 的 记录 ， 保 证 数据 一 致 性 。 
等 到 真正 把 segment 刷 到 磁盘 ， 且 commit 文 件 进行 更 新 的 时 候 ，translog 文 件 才 清 空 。 这 一 步 ， 叫 做 flush。 同 样 ，Elasticsearch 也 提供 了 /_flush 接 口 。 


对 于 flush 操 作 ，Elasticsearch 默 认 设 置 为 : 每 30 分 钟 主动 进行 一 次 flush， 或 者 当 translog 文 件 大 小 大 于 512MB ( 老 版 本 是 200MB) 时 ， 主 动 进行 一 次 flush。 这 两 个 行为 ， 可 以 分 别 通过 
index.translog.flush threshold periodslindex.translog.flush threshold size 参数 修改 。 


如 果 对 这 两 种 控制 方式 都 不 满意 ，Elasticsearch 还 可 以 通过 index.translog.flush_threshold_ops 参 数 ， 控 制 每 收 到 多 少 条 数据 后 flush 一 次 。 
translog 的 一 致 性 
索引 数据 的 一 致 性 通过 translog 保 证 。 那 么 translog 文 件 自己 呢 ? 


默认 情况 下 ，Elasticsearch 每 5 秒 会 强制 刷新 translog 日 志 到 磁盘 上 。 所 以 ， 如 果 数 据 没 有 副本 ， 然 后 又 发 生 故 障 ， 确 实 有 可 能 丢失 5 秒 数 据 。 如 果 你 很 在 意 这 个 情况 ， 首 先 记 得 开 副本 ， 其 次 ， 调 小 
index.gateway.local.sync 设 置 ， 然 后 重启 Elasticsearch 服 务 。 


大 家 可 能 注意 到 了 ， 前 面 一 段 内 容 ， 一 直 写 的 是 “Lucene 索 引 ”。 这 个 区 别 在 于 ，Elasticsearch 为 了 完成 分 布 式 系统 ， 对 一 些 名 词 概念 作 了 变动 。 索 引 成 为 了 整个 集群 级 别 的 命名 ， 而 在 单个 主机 上 的 
Lucene 索 引 ， 则 被 命名 为 分 片 (shard) 。 至 于 数据 是 怎么 识别 到 自己 应 该 在 哪个 分 片 ， 请 阅读 稍 后 8.3 节 有 关 routing 的 内 容 。 


8.2 segment merge 的 影响 


通过 上 节 内 容 ， 我 们 知道 了 数据 怎么 进入 Elasticsearch 并 且 如 何 才能 让 数据 更 快 地 被 检索 使 用 。 其 中 用 一 句 话 概括 了 Lucene 的 设计 思路 就 是 “ 开 新 文件 ”， 但 另 一 个 方面 看 ， 开 新 文件 也 会 给 服务 器 带 
来 负载 压力 。 因 为 默认 每 1 秒 都 会 有 一 个 新 文件 产生 ， 每 个 文件 都 需要 有 文件 句柄 、 内 存 、CPU 使 用 等 各 种 资源 。 一 天 有 86400 秒 ， 设 想 一 下 ， 每 次 请 求 要 扫描 一 遍 86400 个 文件 ， 这 个 响应 性 能 绝对 好 不 


为 了 解决 这 个 问题 ，Elasticsearch 会 不 断 在 后 台 运行 任务 ， 主 动 将 这 些 零 散 的 segment 做 数据 归并 ， 尽 量 让 索引 内 只 保有 少量 的 ， 每 个 都 比较 大 的 ，segment 文 件 。 本 节 介 绍 segment merge 操 作对 
写 入 性 能 的 影响 ， 以 及 其 控制 策略 和 优化 方法 。 


这 个 过 程 是 有 独立 的 线程 来 进行 的 ， 并 不 影响 新 segment 的 产生 。 归 并 过 程 中 ， 索 引 状 态 如 图 8-7 所 示 ， 尚 未 完成 的 较 大 的 segment 是 被 排除 在 检索 可 见 范围 之 外 的 : 


当归 并 完成 ， 较 大 的 这 个 segment 刷 到 磁盘 后 ，commit 文 件 做 出 相应 变更 ， 删 除 之 前 几 个 小 segment， 改 成 新 的 大 segment。 等 检索 请 求 都 从 小 segment 转 到 大 segment 上 以 后 ， 删 除 没 用 的 小 
segment。 这 时 候 ， 索 引 里 segment 数 量 就 下 降 了 ， 状 态 如 图 8-8 所 示 。 
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图 8-7 segments merge 过 程 
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图 8-8 segment merge 完 成 


8.2.1 ”归并 线程 配置 


segment 归 并 的 过 程 ， 需 要 先 读 取 segment， 归 并 计算 ， 再 写 一 遍 segment， 最 后 还 要 保证 刷 到 磁盘 。 可 以 说 ， 这 是 一 个 非常 消耗 磁盘 MO 和 CPU 的 任务 。 所 以 ，Elasticsearch 提 供 了 对 归并 线程 的 限 
速 机 制 ， 确 保 这 个 任务 不 会 过 分 影响 到 其 他 任务 。 


默认 情况 下 ， 归 并 线程 的 限 速配 置 indices.store.throttle.max_bytes_per_sec 是 20MB。 对 于 写 入 量 较 大 ,磁盘 转速 较 高 ， 甚 至 使 用 SSD 盘 的 服务 器 来 说 ， 这 个 限 速 是 明显 过 低 的 。 对 于 ELK stack 应 
用 ， 建 议 可 以 适当 调 大 到 100MB 或 者 更 高 。 


# curl -XPUT http://127.0.0.1:9200/ cluster/settings -d' 
1 
“persistent” : ( 
"indices.store.throttle.max bytes per sec" : “100mb” 
F | 


归并 线程 的 数目 ，Elasticsearch 也 是 有 所 控制 的 。 默 认 数目 的 计算 公式 是 : Math.min (3, Runtime.getRuntime () .availableProcessors () /2) 。 即 服务 器 CPU 核 数 的 一 半 大 于 3 时 ， 启 动 3 个 归并 
线程 ; 否则 启动 跟 CPU 核 数 的 一 半 相 等 的 线程 数 。 相 信 一 般 做 ELK stack 的 服务 器 CPU 合 数 都 会 在 6 个 以 上 。 所 以 一 般 来 说 就 是 3 个 归并 线程 。 如 果 你 确定 自己 磁盘 性 能 跟 不 上 ， 可 以 降低 
index.merge.scheduler.max thread count 配置 ， 免 得 MO 情况 更 加 恶化 。 


8.2.2 ”归并 策略 


归并 线程 是 按照 一 定 的 运行 策略 来 挑选 segment 进 行 归并 的 。 主 要 有 以 下 几 条 : 
* index.merge.policy.floor segment 黑 认 2MB ， 小 于 这 个 大 小 的 segment， 优 先 被 归并 。 
“ index.merge.policy.max_merge_at_once 默 认 一 次 最 多 归并 10 个 segment。 
index.merge.policy.max_merge_at_once_explicit 默 认 optimize 时 一 次 最 多 归并 30 个 segment。 
“ index.merge.policy.max_merged_segment 上 默认 5 GB， 大 于 这 个 大 小 的 segment， 不 用 参与 归并 。optimize 除 外 。 


根据 这 段 策 略 ， 其 实 我 们 也 可 以 从 另 一 个 角度 考虑 如 何 减少 segment 归 并 的 消耗 以 及 提高 响应 的 办 法 : 加 大 flush 间 隔 ， 尽 量 让 每 次 新 生成 的 segment 本 身 大 小 就 比较 大 。 


8.2.3 optimize 接 口 


既然 默认 的 最 大 segment 大 小 是 5GB。 那 么 一 个 比较 庞大 的 数据 索引 ， 就 必然 会 有 为 数 不 少 的 segment 永 远 存在 ， 这 对 文件 句柄 、 内 存 等 资源 都 是 极 大 的 浪费 。 但 是 由 于 归并 任务 太 消耗 资源 ， 所 以 一 
般 不 太 选 择 加 大 index.merge.policy.max_merged segment 配置 ， 而 是 在 负载 较 低 的 时 间 段 ， 通 过 optimize 接 口 ， 强 制 归 并 segment。 


# curl -XPOST http://127.0.0.1:9200/logstash-2015-06.10/_optimize?max_num_ 
segments-1 


由 于 optimize 线 程 对 资源 的 消耗 比 普通 的 归并 线程 大 得 多 ， 所 以 ， 绝 对 不 建议 对 还 在 写 入 数据 的 热 索 引 执 行 这 个 操作 。 这 个 问题 对 于 ELK stack 来 说 非常 好 办 ， 一 般 索 引 都 是 按 天 分 割 的 。 更 合适 的 任务 
定义 方式 请 阅读 本 书 稍 后 的 10.6 节 “curator 工 具 ” 


8.3 routing 和 replica 的 读 写 过 程 


之 前 两 节 ， 完 整 介绍 了 在 单个 Lucene 索 引 ， 即 Elasticsearch 分 片 内 的 数据 写 入 流程 。 现 在 彻底 回 到 Elasticsearch 的 分 布 式 层 面 上 来 ， 当 一 个 Elasticsearch 节 点 收 到 一 条 数据 的 写 入 请 求 时 ， 它 是 如 何 确 
认 这 个 数据 应 该 存储 在 哪个 节点 的 哪个 分 片上 的 ? 本 节 介绍 数据 写 入 过 程 中 ，Elasticsearch 是 如 何 确定 具体 的 节点 位 置 ， 以 及 副本 的 控制 策略 。 


8.3.1 路 由 计算 


作为 一 个 没有 额外 依赖 的 简单 的 分 布 式 方案 ，Elasticsearch 在 这 个 问题 上 同样 选择 了 一 个 非常 简洁 的 处 理 方式 ， 对 任 一 条 数据 计算 其 对 应 分 片 的 方式 如 下 : 


shard = hash (routing) $ number of primary shards 


每 个 数据 都 有 一 个 routing 参 数 ， 默 认 情 况 下 ， 就 使 用 其 id 值 。 将 其 id 值 计 算 哈 希 后 ， 对 索引 的 主 分 片 数 取 余 ， 就 是 数据 实际 应 该 存储 到 的 分 片 ID。 


由 于 取 余 这 个 计算 ， 完 全 依赖 于 分 母 ， 所 以 导致 Elasticsearch 索 引 有 一 个 限制 ， 索 引 的 主 分 片 数 ， 不 可 以 随意 修改 。 因 为 一 旦 主 分 片 数 不 一 样 ， 所 以 数据 的 存储 位 置 计 算 结果 都 会 发 生 改变 ， 索 引 数据 
就 完全 不 可 读 了 。 


8.32 副本 一 致 性 


作为 分 布 式 系统 ， 数 据 副本 可 算是 一 个 标 配 。Elasticsearch 数 据 写 入 流程 ， 自 然 也 涉及 副本 。 在 有 副本 配置 的 情况 下 ， 数 据 从 发 向 Elasticsearch 节 点 ， 到 接 到 Elasticsearch 节 点 响应 返回 ， 流 向 如 下 
( 见 图 8-9) : 


NODE 1- 言 MASTER NODE 2 


RO 


8-0 数据 写 入 流程 


1) 客户 端 请 求 发 送 给 Node 1 节点 ， 注 意图 中 Node 1 是 Master 节 点 ， 实 际 完全 可 以 不 是 。 


2) Node 1 用 数据 的 id 取 余 计算 得 到 应 该 将 数据 存储 到 shard 0 上 。 通 过 cluster state 信 息 发 现 shard 0 的 主 分 片 已 经 分 配 到 了 Node 3 上 。Node 1 转发 请 求 数据 给 Node 3, 


3) Node 3 完成 请 求 数据 的 索引 过 程 ， 存 入 主 分 片 0。 然 后 并 行 转发 数据 给 分 配 有 shard 0 的 副本 分 片 的 Node 1 和 Node 2。 当 收 到 任 一 节点 汇报 副本 分 片 数据 写 入 成 功 ，Node 3 即 返 回 给 初始 的 接收 节 
点 Node 1， 宣 布 数据 写 入 成 功 。Node 1 返回 成 功 响应 给 客户 端 。 


这 个 过 程 中 ， 有 几 个 参数 可 以 用 来 控制 或 变更 其 行为 。 


“ replication: 通过 在 客户 端 发送 请 求 的 URL 中 加 上 replication=async， 可 以 控制 Node 3 在 完成 本 机 主 分 片 写 入 后 ， 就 返回 给 Node 1 宣布 写 入 成 功 。 这 个 参数 看 似 可 以 提高 Elasticsearch 接 收 数据 写 入 的 性 
能 ， 但 事实 上 ， 由 于 Elasticsearch 的 副本 数据 写 入 也 是 要 经 过 完成 索引 过 程 的 ， 一 旦 由 于 发 送 过 多 数据 ， 主 机 负载 偏 高 导致 某 块 数据 写 入 有 异常 ， 可 能 整个 主机 的 CPU 都 会 舰 高 ， 导 致 分 配 到 这 人 台 主 机 上 其 他 
主 分 片 的 数据 都 无 法 高 性 能 完成 ， 最 终 反而 拖累 了 整体 的 写 入 性 能 。 从 Elasticsearch 1.6 版 本 开始 ， 该 参数 已 经 被 标记 为 废弃 ，2.0 版 预计 将 正式 删除 该 参数 。 


: consistency: 上 面 示例 中 ， 两 个 副本 分 片 只 要 有 一 个 成 功 ， 就 可 以 返回 给 客户 端 了 。 这 点 也 是 有 配置 项 的 。 其 默认 值 的 计算 来 源 如 下 : 


int ( (primary + number of replicas) /2) +1 


根据 需要 ， 也 可 以 将 参数 设置 为 one， 表 示 仅 写 完 主 分 片 就 返回 ， 等 同 于 async; 还 可 以 设置 为 all， 表 示 等 所 有 副本 分 片 都 写 完 才能 返回 。 


timeout: 如 果 集 群 出 现 异 常 ， 有 些 分 片 当前 不 可 用 ，Elasticseatch 默 认 会 等 待 1 分 钟 看 分 片 能 否 恢复 。 可 以 使 用 timeout=30s 参 数 来 缩短 这 个 等 待 时 间 。 


副本 配置 和 分 片 配置 不 一 样 ， 是 可 以 随时 调整 的 。 有 些 较 大 的 索引 ， 甚 至 可 以 在 做 optimize 前 ， 先 把 副本 全 部 取消 掉 ， 等 optimize 完 后 ， 再 重新 开启 副本 ， 节 约 单个 segment 的 重复 归并 消耗 。 


# curl -XPUT http://127.0.0.1:9200/10gstash-mweibo-2015.05.02/ settings -d '{ “index” : ( “number of replicas" : 0 
y 


84 shard 的 allocate 控 制 


本 节 介绍 分 片 在 集群 中 的 分 配 策略 ， 手 动 控制 方式 ， 以 及 由 此 衍生 出 来 的 Elasticsearch 读 写 分 离 方 案 。 


某 个 shard 分 配 在 哪个 节点 上 ， 一 般 来 说 ， 是 由 Elasticsearch 自 动 决定 的 。 以 下 几 种 情况 会 触发 分 配 动 作 : 
“ 新 索引 生成 。 


“ 索引 的 删除 。 


“节点 增 减 引 发 的 数据 均衡 。 
Elasticsearch 提 供 了 一 系列 参数 详细 控制 这 部 分 逻辑 : 
* clustertrouting.allocation.enable 参 数 用 来 控制 允许 分 配 哪 种 分 片 。 默 认 是 al。 可 选项 还 包括 primaties 和 new_primaries。none 则 彻底 拒绝 分 片 。 该 参数 的 作用 ， 本 书 稍 后 集群 升级 章节 会 有 说 明 。 


“cluster.routing.allocation.allow_rebalance 参 数 用 来 控制 什么 时 候 允 许 数据 均衡 。 默 认 是 indices_all_active， 即 要 求 所 有 分 片 都 正常 启动 成 功 以 后 ， 才 可 以 进行 数据 均衡 操作 ， 否 则 的 话 ， 在 集群 重启 阶段 
会 浪费 太 多 流量 了 。 


“cluster.routing.allocation.cluster_concurrent_rebalance 参 数 用 来 控制 集群 内 同时 运行 的 数据 均衡 任务 个 数 。 上 默认 是 2 个 。 如 果 有 节点 增 减 ， 且 集群 负载 压力 不 高 的 时 候 ， 可 以 适当 加 大 。 


“cluster.routing.allocation.node_initial_primaries_recoveries 参 数 用 来 控制 节点 重启 时 ， 允 许 同时 恢复 几 个 主 分 片 。 默 认 是 4 个 。 如 果 节 点 是 多 磁盘 ， 且 I/O 〇 压力 不 大 ， 可 以 适当 加 大 。 


“cluster.routing.allocation.node_concurrent_recoveries 参 数 用 来 控制 节点 及 分 片 重启 恢复 以 外 其 他 情况 下 ， 允 许 同时 运行 的 数据 恢复 任务 。 上 默认 是 2 个 。 所 以 ， 节 点 重启 时 ， 可 以 看 到 主 分 片 迅 速 恢复 完 
成 ， 副 本 分 片 的 恢复 却 很 慢 。 除 了 副本 分 片 本 身 数 据 要 通过 网 络 复制 以 外 ， 并 发 线程 本 身 也 减少 了 一 半 。 当 然 ， 这 种 设置 也 是 有 道理 的 一 一 主 分 片 一 定 是 本 地 恢复 ， 副 本 分 片 却 需要 走 网 络 ， 带 宽 是 有 限 
的 。 从 Elasticsearch 1.6 开 始 ， 冷 索引 的 副本 分 片 可 以 本 地 恢复 ， 这 个 参数 也 就 是 可 以 适当 加 大 了 。 


“indices.recovery.concurrent_streams 参 数 用 来 控制 节点 从 网 络 复制 恢复 副本 分 片 时 的 数据 流 个 数 。 默 认 是 3 个 。 可 以 配合 上 一 条 配置 一 起 加 大 。 


“ indices.recovery.max_bytes_per_sec 参 数 用 来 控制 节点 恢复 时 的 速率 。 默 认 是 40MB。 显 然 是 比较 小 的 ， 建 议 加 大 。 


此 外 ，Elasticsearch 还 有 一 些 其 他 的 分 片 分 配 控制 策略 。 比 如 以 tag 和 rack_id 作 为 区 分 等 。 一 般 来 说 ，ELK stack 场 景 中 使 用 不 多 。 运 维 人 员 可 能 比较 常见 的 策略 有 两 种 : 


节点 数据 安全 ，Elasticsearch 会 定时 (clusterinfo.update.interval ， 默 认 30 秒 ) 检查 一 下 各 节点 的 数据 目录 磁盘 使 用 情况 。 在 达到 cluster.routing.allocation.disk.watermark.low (默认 
8599) 的 时 候 ， 新 索引 分 片 就 不 会 再 分 配 到 这 个 节点 上 了 。 在 达到 cluster.routing.allocation.disk.watermark.high (默认 90%) 的 时 候 ， 就 会 触发 该 节点 现存 分 片 的 数据 均衡 ， 把 数据 挪 到 其 他 节点 上 去 。 这 两 个 值 
不 但 可 以 写 百分比 ， 还 可 以 写 具体 的 字 节 数 。 有 些 公司 可 能 出 于 成 本 考虑 ， 对 磁 瘟 使 用 率 有 一 定 的 要 求 ， 需 要 适当 抬 高 这 个 配置 : 


# curl -XPUT localhost: 9200/ cluster/settings -d 24 "transient" : { 
"cluster.routing.allocation.disk.watermark.low" : “85%” , 
"cluster.routing.allocation.disk. watermark. high" 
"cluster.info.update.interval" "1m 

P j 


“ 热 索引 分 片 不 均一 一 默认 情况 下 ，Elasticsearch 集 群 的 数据 均衡 策略 是 以 各 节点 的 分 片 总 数 (indices all active). 作为 基准 的 。 这 对 于 搜索 服务 来 说 无 疑 是 均衡 搜索 压力 提高 性 能 的 好 办 法 。 但 是 对 于 
ELK stack 场 景 ， 一 般 压 力 集 中 在 新 索引 的 数据 写 入 方面 。 正 常 运行 的 时 候 ， 也 没有 问题 。 但 是 当 集 群 扩容 时 ， 新 加 入 集群 的 节点 ， 分 片 总 数 远 远 低 于 其 他 节点 。 这 时 候 如 果 有 新 索引 创建 ，Elasticsearch 的 默 
认 策 略 会 导致 新 索引 的 所 有 主 分 片 几 乎 全 分 配 在 这 台新 节点 上 。 整 个 集群 的 写 入 压力 ， 压 在 一 个 节点 上 ， 结 果 很 可 能 是 这 个 节点 直接 被 压 死 ， 集 群 出 现 异常 。 所 以 ， 对 于 ELK stack 场 景 ， 强 烈 建议 大 家 预先 
计算 好 索引 的 分 片 数 后 ， 配 置 好 单 节 点 分 片 的 限额 。 比 如 ， 一 个 5 节点 的 集群 ， 索 引 主 分 片 10 个 ， 副 本 1 份 。 则 平均 下 来 每 个 节点 应 该 有 4 个 分 片 ， 那 么 就 配置 : 


# curl -s -XPUT http: //127.0.0.1:9200/10gstash-2015.05.08/ -settings sd tr 
"index" : ( "routing. allocation.total shards per i node" : J 
p 


注意 ， 这 里 配置 的 是 5 而 不 是 4。 因 为 我 们 需要 预防 有 机 器 故障 ， 分 片 发 生 迁 移 的 情况 。 如 果 写 的 是 4， 那 么 分 片 迁移 会 失败 。 


8.4.1 reroute 接 口 


上 面 说 的 各 种 配置 ， 都 是 从 策略 层面 ， 控 制 分 片 分 配 的 选择 。 在 必要 的 时 候 ， 还 可 以 通过 Elasticsearch 的 reroute 接 口 ， 手 动 完 成 对 分 片 的 分 配 选 择 的 控制 。 


reroute 接 口 支持 三 种 指令 : allocate、move 和 cancel， 常 用 的 是 allocate 和 move。 


. allocate 指 令 : 因为 负载 过 高 等 原因 ， 有 时 候 个 别 分 片 可 能 长 期 处 于 UNASSIGNED 状 态 ， 我 们 就 可 以 手动 分 配 分 片 到 指定 节点 上 。 上 默认 情况 下 只 允许 手动 分 配 副本 分 片 ， 所 以 如 果 是 主 分 片 故障 ， 需 要 
单独 加 一 个 allow_primary 选 项 : 


# curl -XPOST 127.0.0.1:9200/_cluster/reroute -d '{ “commands” : [ { 
“allocate” : 
{ “index” : “logstash-2015.05.27” , “shard : 61, “node : “10.19.0.77”， “allow primary" 
: true 


1] 
p 


注意 ， 如 果 是 历史 数据 的 话 ， 请 提前 确认 一 下 哪个 节点 上 保留 有 这 个 分 片 的 实际 目录 ， 且 目录 大 小 最 大 。 然 后 手动 分 配 到 这 个 节点 上 。 以 此 减少 数据 丢失 。 


move A: 因为 负载 过 高 ， 磁 盘 利用 率 过 高 ， 服 务 器 下 线 ， 更 换 磁 人 盘 等 原因 ， 可 以 会 需要 从 节点 上 移 走 部 分 分 片 : 


# curl -XPOST 127.0.0.1:9200/ cluster/reroute -d '( "commands" : [ { 
"move" 
{ 
“index” : “logstash-2015.05.22” , “shard : 0, "from node" 
node" : ^"10.19.0.104" Bi 


842 ” 冷 热 数据 的 读 写 分 离 


钟 。 


*10.19.0.81" , "to. 


Elasticsearch 集 群 一 个 比较 突出 的 问题 是 : 用 户 做 一 次 大 的 查询 的 时 候 ， 非 常 大 量 的 读 I/O 以 及 聚合 计算 导致 机 器 Load 升 高 ，CPU 使 用 率 上 升 ， 会 影响 阻塞 到 新 数据 的 写 入 ， 这 个 过 程 甚至 会 持续 几 分 


所 以 ， 可 能 需要 仿照 MySQL 集 群 一 样 ， 做 读 写 分 离 。 


实施 步骤 如 下 : 


1) N 台 机 器 做 热 数据 的 存储 ， 上 面 只 放 当 天 的 数据 。 这 N 台 热 数 据 节 点 上 面 的 elasticsearc.yml 中 配置 node.tag: hot 


2) 之 前 的 数据 放 在 另外 的 M 台 机 器 上 。 这 M 人 台 冷 数据 节点 中 配置 node.tag: stale 


3) 模板 中 控制 对 新 建 索引 添加 hot 标 签 : 


"order" : 0, 

"template" : "'*", 

"settings" : ( 
"index.routing.allocation.require.tag' : “hot” 


} 
} 


4) 每 天 计划 任务 更 新 索引 的 配置 ， 将 tag 更 改 为 stale， 索 引 会 自动 迁移 到 M 台 冷 数据 节点 


# curl -XPUT http://127.0.0.1:9200/indexname/ settings -d' 
{ "index" : { 
"routing' : ( 
"allocation" : ( 
"require" : ( 
"tag' : "stale" 
} 
j 
} 
} 
p 


这 样 ， 写 操作 集中 在 N 台 热 数据 节点 上 ， 大 范围 的 读 操作 集中 在 M 人 台 冷 数据 节点 上 。 避 免 了 堵塞 影响 。 


该 方案 运用 的 ， 是 Elasticsearch 中 的 allocation filter 功 能 ， 详 细 说 明 见 : https://www.elastic.co/guide/en/elasticsearch/reference/master/shard-allocation-filtering.html 


85 ”自动 发 现 的 配置 


Elasticsearch 是 一 个 P2P 类 型 (使 用 gossip 协 议 ) 的 分 布 式 系统 ， 除 了 集群 状态 管理 以 外 ， 其 他 所 有 的 请 求 都 可 以 发 送 到 集群 内 任意 一 台 节 点 上 ， 这 个 节点 可 以 自己 找到 需要 转发 给 哪些 节点 ， 并 且 直 


接 跟 这 些 节 点 通信 。 所 以 ， 从 网 络 架构 及 服务 配置 上 来 说 ,构建 集群 所 需要 的 配置 极其 简单 。 在 无 阻碍 的 网 络 下 ， 所 有 配置 了 相同 cluster.name 的 节点 都 自动 归属 到 一 个 集群 中 。 本 节 介 绍 Elasticsearch 集 
群 的 两 种 自动 发 现 策略 。 


8.5.1 multicast 方 式 


息 。 


只 配置 clustername 的 集群 ， 其 实 就 是 采用 了 默认 的 自动 发 现 协 议 ， 即 组 播 (multicast) 方式 。 节 点 会 在 本 机 所 有 网 卡 接口 上 ， 使 用 组 播 地 址 224.2.2.4， 以 54328 端 口 建立 组 播 组 发 送 clustername 信 


但 是 ， 并 不 是 所 有 的 路 由 交换 设备 都 支持 并 且 开 启 了 组 播 信息 传输 ! 甚至 可 以 说 ， 默 认 情 况 下 ， 都 是 不 开启 组 播 信息 传输 的 。 


所 以 在 没有 网 络 工程 师 帮助 的 情况 下 ，Elasticsearch 以 默认 组 播 方式 ， 只 有 在 同一 个 交换 机 下 的 节点 ， 能 自动 发 现 ， 跨 交换 机 的 节点 ， 是 无 法 收 到 组 播 信息 的 。 


此 外 ， 由 于 节点 是 以 所 有 网 卡 接口 发 送 组 播 信 息 ， 而 操作 系统 内 核 层面 对 组 播 信息 来 源 的 验证 中 ， 却 对 网 卡 接口 地 址 有 一 步 校 验 ， 有 可 能 发 生 内 核 层 面 的 信息 丢弃 ， 导 致 多 网 卡 的 节点 也 无 法 正常 使 


组 播 方式 。 


8.5.2 unicast 方 式 


能 ， 所 以 gossip router 角 色 并 不 需要 单独 配置 ， 每 个 Elasticsearch 节 点 都 可 以 担任 。 所 以 ， 采 


除了 组 播 方式 ，Elasticsearch 还 支持 单 播 (unicast) 方式 。 配 置 里 提供 几 人 台 节 点 的 地 址 ，Elasticsearch 将 其 视 作 gossip router 角 色 ， 借 以 完成 集群 的 发 现 。 由 于 这 只 是 Elasticsearch 内 一 个 很 小 的 功 


此 外 ， 考 虑 到 节点 有 时 候 因为 高 负载 、 慢 GC 等 原因 ， 可 能 会 有 偶尔 没 及 时 响应 ping 包 ， 一 


单 播 方式 的 集群 ， 各 节点 都 配置 相同 的 几 个 节点 列表 作为 router 即 可 。 


股 建 议 稍微 加 大 Fault Detection 的 超时 时 间 ， 如 下 所 示 : 


discovery.zen.minimum master nodes: 3 
discovery.zen.ping.timeout: 100s 

discovery.zen.fd.ping timeout: 100s 
discovery.zen.ping.multicast.enabled: false 
discovery.zen.ping.unicast.hosts: [ "10.19.0.97" , "10.19.0.98" ] 


第 9 章 ”数据 接口 用 例 


stack 场 景 下 ， 数 据 的 写 入 和 查询 分 别 由 Logstash 和 Kibana 代 劳 ， 但 作为 测试 、 调 研 和 排 错时 的 基本 功 ， 还 是 需要 了 解 一 下 Elasticsearch 的 增删 改 查 用 法 的 。 


增删 改 查 操 作 


虽然 大 多 数 时 候 我 们 都 是 通过 Logstash 导 入 数据 ， 但 是 运 维 人 员 依然 需要 掌握 一 些 Elasticsearch 接 口 ， 这 些 接口 在 日 常 维护 、 架 构 变更 等 任务 中 起 到 特殊 的 作用 。 由 于 ELK stack 场 景 对 相关 性 打分 要 求 
不 高 ， 本 章 着 重 介 绍 增删 改 查 、 搜 索 请 求 、 脚 本 、 重 建 索引 、Spark Streaming 交 互 。 


增删 改 查 是 数据 库 的 基础 操作 方法 。Elasticsearch 虽 然 不 是 数据 库 ， 但 是 很 多 场合 下 ， 都 被 人 们 当做 一 个 文档 型 NoSQIL 数 据 库 在 使 用 ， 原 因 自 然 是 因为 在 接口 和 分 布 式 架构 层面 有 相似 性 。 虽 然 在 ELK 


1 数据 写 入 


Elasticsearch 的 一 大 特点 ， 就 是 全 RESTful 接 口 处 理 JSON 请 求 。 所 以 ， 数 据 写 入 非常 简单 : 


# curl -XPOST http://127.0.0.1:9200/10gstash-2015.06.21/testlog -d '{ "date" : “1434966686000” , “user” : “chenlin7” , “mesg : “first message into Elasticsearch" 
' 

命令 返回 响应 结果 为 : 

{ “_index” : "logstash- 2015.06.21" , " type" : "testlog' , " id" : "AU4ew3h2nBE6nOqcyVJK" , “_ 


version" :1, “created” :true) 


2 数据 获取 


可 以 看 到 ， 在 数据 写 入 的 时 候 会 返回 该 数据 的 ijd。 这 是 后 续 用 来 获取 数据 的 关键 : 


# curl -XGET http://127.0.0.1:9200/logstash-2015.06.21/testlog/AU4ew3h2nBE6n0qcyVJK 


命令 返回 响应 结果 为 : 


{ “_index” : "logstash-2015.06.21" , ' type' : "testlog , ^ ig E "AU4ew3h2nBE6nOqcyVOK" " b 


version” :1, "found" :true, " source" :( "date" : “1434966686000” , "user' :  "chenlin7' , “mesg” : “first message into Elasticsearch" 


}} 


_source 里 的 内 容 ， 正 是 之 前 写 入 的 数据 。 


如 果 觉 得 这 个 返回 结果 看 起 来 有 点 太 过 麻烦 ， 可 以 使 用 curl-XGET http://127.0.0.1: 9200/logstash-2015.06.21/testlog/AU4ew3h2nBE6n0qcyVJK/_source 来 指明 只 获取 源 数据 部 分 。 


更 进一步 ， 如 果 你 只 想 看 数据 中 的 部 分 字段 内 容 ， 可 以 使 用 curl-XGET http://127.0.0.1: 9200/logstash-2015.06.21/testlog/AU4ew3h2nBE6n0qcyVJKfields=user，mesg 来 指明 获取 字段 ， 结 果 如 


{ “_index” : “logstash- 2015.06.21" , ,type” : "testlog' ,“ id" : " AU4ew3h2nBEGnOqcyVJK" ps 
version" :1, “found” :true, "fields" :{ “user” :[ "chenlin7" ], “mesg” :[ “first message 
into Elasticsearch' ]}} 


3 数据 删除 


要 删除 数据 ， 修 改 发 送 的 HTTP 请 求 方法 为 DELETE 即 可 : 


# curl -XDELETE http://127.0.0.1:9200/10gstash-2015.06.21/testlog/AU4ew3h2nBE6nO 
qcyVJK 


删除 不 单 针 对 单条 数据 ， 还 可 以 删除 整个 type 乃 至 整个 索引 ， 甚 至 可 以 用 通配符 : 


# curl -XDELETE http://127.0.0.1:9200/logstash-2015.06.0* 


4 数据 更 新 


已 经 写 过 的 数据 ， 也 是 可 以 修改 的 。 有 两 种 办 法 ， 一 种 是 全 量 提交 ， 即 指明 _id 再 发 送 一 次 写 入 请 求 : 


# curl T http: //A27. 0.0.1: 9200/1ogstash- 2015.06. .21/testlog/AU4ew3h2nBE6nOqcyVJK 
-d '{ “date : “1434966686000” , "user" : “chenlin7” , “mesg” first message into Elasticsearch but version 2“ 
p 


另 一 种 是 局 部 更 新 ， 使 用 /update 接 


# curl -XPOST 'http: //A21. 0. 0.1: 9200/1ogstash- 2015. 06. 21/testlog/AU4ew3h2nBE6nO0qcyVJK/ - 
update' -d '( "doc : { "user E someone" 
H i 


或 者 


# curl -XPOST 'http://127.0.0.1:9200/logstash-2015.06.21/testlog/AU4ew3h2nBE6n0qcyVJK/_ 
update' -d '( "script" : “ctx. source.user = V' someoneN “ 


p 


9.2 ”搜索 请 求 


上 节 介绍 的 都 是 针对 单条 数据 的 操作 。 在 Elasticsearch 环 境 中 ， 更 多 的 是 搜索 和 聚合 请 求 。 在 之 前 章节 中 ， 我 们 也 介绍 过 数据 获取 和 数据 搜索 的 一 点 


区 


EUH 


刚 写 入 的 数据 ， 


可 以 通过 translog 立 刻 获 


取 ， 但 是 却 要 等 到 refresh 成 为 一 个 segment 后 才能 被 搜索 到 。 本 节 就 介绍 Elasticsearch 的 搜索 语法 。 


9.2.1 EVER 


Elasticsearch 的 搜索 请 求 有 简易 语法 和 完整 语法 两 种 方式 。 简 易 语 法 是 Kibana 上 最 常用 的 方式 ， 一 定 要 学 会 。 而 在 命令 行 里 ， 我 们 可 以 通过 最 简单 的 方式 来 做 到 。 还 是 上 节 输入 的 数据 : 


# curl -XGET http://127.0.0.1:9200/10gstash-2015.06.21/testlog/ search?g-first 


可 以 看 到 返回 结果 : 


“total” :27, “successful” :27, “failed” : 


{ “took” :240, "timed out" :false, * shards" 
.11506981, “hits” :[( " index' : "logstash- 


0), "hits" :( "total" :1, "max score" : 


2015.06.21” , " type" : 'testlog , " id' : 'AU4ew3h2nBE6nOqcyVOK  , 
” score" :0.11506981, " source" :( T 
"date" : “1434966686000” , 
“user” : “chenlin7”， 
“mesg” : “first message into Elasticsearch" 


还 可 以 用 下 面 语句 搜索 ， 结 果 是 一 样 的 。 


# curl -XGET http://127.0.0.1:9200/10gstash-2015.06.21/testlog/ search?q-user: "chenlin7" 


1.querystring 语 法 


上 例 中 ，q? = 后 面 写 的 就 是 querystring 语 法 。 鉴 于 这 部 分 内 容 会 在 Kibana 上 经 常 使 用 ， 这 里 详细 解析 一 下 语法 : 


:全文 检索 : 直接 写 搜索 的 单词 ， 如 上 例 中 的 first。 

“ 单字 段 的 全 文 检索 : 在 搜索 单词 之 前 加 上 字段 名 和 冒号 ， 比 如 ， 如 果 知 道 单 词 first 肯 定 出 现在 mesg 字 段 ， 可 以 写作 mesg: fint. 

“ 单字 段 的 精确 检索 : 在 搜索 单词 前 后 加 双 引 号 ， 比 如 user: "chenlin7"。 

“ 多 个 检索 条 件 的 组 合 : 可 以 使 用 NOT、AND 和 OR 来 组 合 检 索 ， 注 意 必须 是 大 写 。 比 如 user:  ("chenlin7"OR"chenlin") AND NOT mesg: firsto 
“ 字段 是 否 存 在 : _exists_: user 表 示 要 求 uset 字 段 存 在 ，_missing_: user 表 示 要 求 user 字 段 不 存在 。 

“ 通配符 : 用 表示 单字 母 ，* 表 示 任 意 个 字母 。 比 如 firt mess*。 


“ 正则: 需要 比 通配符 更 复杂 一 点 的 表达 式 ， 可 以 使 用 正则 。 比 如 mesg: /mes{f2}ages/。 注 意 Elasticsearch 中 正则 性 能 很 差 ， 而 且 支持 的 功能 也 不 是 特别 强大 ， 尽 量 不 要 使 用 。Elasticseatch 支 持 的 正则 语 


法 见 : https:/ /www.elastic.co/ guide/en/elasticsearch/reference/current/query-dsl-regexp-query.htmlféregexp-syntax o 
' 近似 搜索 : 用 ~ 表示 搜索 单词 可 能 有 一 两 个 字母 写 得 不 对 ， 请 Elasticsearch 按 照相 似 度 返回 结果 。 比 如 ftist~。 


' 范围 搜索 : 对 数值 和 时 间 ，Elasticsearch 都 可 以 使 用 范围 搜索 ， 比 如 : rtt: >300、date: ["now-6h"TO"now"} 等 。 其 中 ,表示 端点 数值 包含 在 范围 内 ，{} 表 示 端 点 数值 不 包含 在 范围 内 。 


Elasticsearch 支 持 各 种 类 型 的 检索 请 求 ， 除 了 可 以 用 querystring 语 法 表达 以 外 ， 还 有 很 多 其 他 类 型 ， 具 体 列表 和 示例 可 参 


: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-queries.html, 


a 


作为 最 简单 和 常用 的 示例 ， 这 里 展示 一 下 term query 的 写法 ， 相 当 于 querystring 语 法 中 的 user: "chenlin7": 


# curl -XGET http://127.0.0.1:9200/ search -d ' 
{ 
"query' : { 
“term” : { 
"user" : "chenlin7" 
} 
} 
p 


9.22 聚合 请 求 


在 检索 范围 确定 之 后 ，Elasticsearch 还 支持 对 结果 集 做 聚合 查询 ， 返 回 更 直接 的 聚合 统计 结果 。 在 Elasticsearch 1.0 版 本 之 前 ， 这 个 接口 叫 facet，1.0 版 本 之 后 ， 这 个 接口 改 为 aggregation。 


Kibana 分 别 在 v3 中 使 用 facet，v4 中 使 用 aggregation。 不 过 总 的 来 说 ，aggregation 是 facet 接 口 的 强化 升级 版 本 ， 我 们 直接 了 解 aggregation 即 可 。 本 书 第 17 章 也 会 介绍 如 何在 Kibana 的 v3 版 本 中 使 
aggregation 接 口 做 二 次 开发 。 


aggregation 分 为 bucket 和 metric 两 种 ， 分 别 用 作词 元 划分 和 数值 计算 。 而 其 中 的 bucket aggregation 还 支持 在 自身 结果 集 的 基础 上 径 加 新 的 aggregation。 这 就 是 aggregation 领 先 于 facet 的 地 方 。 
比如 实现 一 个 时 序 百分比 统计 ， 在 facet 接 口 无 法 直接 完成 ， 而 在 aggregation 接 口 就 很 简单 了 ， 如 下 所 示 : 


# curl -XPOST 'http://127.0.0.1:9200/logstash-2015.06.22/_search?size=0&pretty' -d'( "aggs" : ( 
"percentile over time" : ( 
"date histogram : ( 


"field" : "Qtimestamp' , 
"interval" "1h" 
Eu 
"aggs t d f 
percentile one time td 
“percentiles” : ( 
“field” : “requesttime” 


得 到 的 结果 如 下 : 


{ “took” : 151595, “timed out” : false, “ shards” : { “total” : 81, “successful” : 81, "failed" : 0 


), "hits" : ( “total” : 3307142043, "max score” : 1.0, "hits" : [ ] 
), “aggregations” : ( "percentile over time" : { “buckets” : [ ( "key as string" :  '22/Jun/2015:22:00:00 40000" , "key" : 1435010400000, "doc count" : 459273981, "percenti 
} 
} 
), ( "key as string' : “23/Jun/2015:00:00:00 +0000” , “key” : 1435017600000, "doc count” : 768620219, "percentile one time" : { “values” : ( "1.0" : 0.004, “5.0” : 0. 
} 
} 
}, ( "key as string' : “23/Jun/2015:02:00:00 +0000” , “key” : 1435024800000, "doc count” : 849467060, "percentile one time" : { “values” : ( "1.0" : 0.004, “5.0” : 0. 


Elasticsearch 目 前 能 支持 的 聚合 请 求 列 表 ， 参 见 : https///www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html, 


9.3 脚本 


Elasticsearch 中 ， 可 以 使 用 自 定 义 脚本 扩展 功能 ， 包 括 评分 、 过 滤 函 数 和 聚合 字段 等 方面 。 作 为 ELK stack 场 景 ， 我 们 只 介绍 在 聚合 字段 方面 使 用 脚本 的 方式 。 


93.1 动态 提交 


最 简单 易 用 的 方式 ， 就 是 在 正常 的 请 求 体 中 把 field 换 成 script 提 交 。 比 如 一 个 标准 的 terms agg 改 成 script 方 式 ， 写 法 如 下 : 


# curl 127.0.0.1:9200/10gstash-2015.06.29/ search -d '( “aggs” : ( 


"clientip toplO" : ( 
“terms” : 
“script” : "doc['clientip'].value" 


$ 
» 


在 script 中 ， 有 两 种 方式 引用 数据 : doc['clientip'].value 和 _source.clientip。 其 区 别 在 于 : doc[].value 读 取 fielddata 内 的 数据 ，_source.obj.attr 读 取 _source 的 JSON 内 容 。 这 也 意味 着 ， 前 者 必须 读 取 
的 是 最 终 的 词 元 字段 数据 ， 而 后 者 可 以 返回 任意 的 数据 结构 。 


Qus 


因为 读 取 的 是 fielddata， 所 以 如 果 有 分 词 的话 ，docl[.value 读 取 到 的 是 分 词 后 的 数据 。 因 此 ， 应 按 需 使 用 doc[clientip.raw].value 写 法 。 


93.2 ”固定 文件 


Elasticsearch 在 1.4.0 之 前 ， 默 认 脚 本 引 警 是 使 用 mvel 语 言 ， 随 后 改 成 groovy， 但 是 从 1.4.3 开 始 ， 由 于 安全 漏洞 关 掉 了 动态 提交 功能 ， 只 能 使 用 固定 文件 方式 运行 。 


为 了 和 动态 提交 的 语法 有 区 别 ， 调 用 固定 文件 的 写法 如 下 : 


# curl 127.0.0.1:9200/10gstash-2015.06.29/ search -d '{ "aggs" : ( 
"clientip subnet topl0" id 


"terms" : ( 
“script file" : "getvalue" , 
"lang  : "groovy , 
"params" : 
"fieldname' : "clientip.raw' , 


“pattern” : "^ ( (? : N3(1,3]N.2) (3) N.Ndt1,3)5" 


上 例 要 求 在 Elasticsearch 集 群 的 所 有 数据 节点 上 ， 都 保存 一 个 /etc/elasticsearch/scripts/getvalue.groovy 文 件 ， 并 且 该 脚本 文件 可 以 接收 fieldname 和 pattern 两 个 变量 。 试 举例 如 下 : 


#!/usr/bin/env groovy 
matcher = ( doc[fieldname].value =~ /${pattern}/ ) 
if (matcher.matches () ) | 
matcher[0] [1] 
} 


Qus 


Elasticsearch 进 程 默 认 每 分 钟 扫描 一 次 /etc/elasticsearch/scripts/ 目 录 ， 并 尝试 加 载 该 目录 下 的 所 有 文件 作为 script。 所 以 ， 不 要 在 该 目录 内 做 文件 编辑 等 工作 ， 不 要 分 发 .svn 等 目录 到 生成 环境 ,这些 临时 或 
者 隐藏 文件 会 被 Elasticsearch 进 程 加 载 然后 报错 。 


9.3.3 ”其 他 语言 


Elasticsearch 支 持 通过 插件 方式 扩展 脚本 语言 的 支持 ， 目 前 默认 自 带 的 语言 包括 : 
* lucene expression 
* groovy 


: mustache 


而 Github 上 目前 已 有 以 下 语言 插件 支持 ， 基 本 覆盖 了 所 有 JVM 上 的 可 用 语言 : 
* https://github.com/elastic/elasticsearch-lang-mvel 


* https://github.com/elastic/elasticsearch-lang-javascript 


* https:/ /github.com/elastic/elasticsearch-lang-python 


* https:/ /github.com/hiredman/elasticsearch-lang-clojure 


* https:/ /github.com/felipehummel/elasticsearch-lang-scala 


* https:/ /github.com/fcheung/elasticsearch-jruby 


94 ”重建 索引 


Elasticsearch 本 身 不 提供 对 索引 的 rename、mapping、alter 等 操作 。 所 以 ， 如 果 需 要 对 全 索引 数据 进行 导出 ， 或 者 修改 某 个 已 有 字段 的 mapping 设 置 等 ， 只 能 通过 scroll AP| 导 出 全 部 数据 ， 然 后 重新 
做 一 次 索引 写 入 。 这 个 过 程 叫做 reindex (8 


既然 没有 直接 的 方式 ， 那 么 自然 只 能 使 


E 建 索引 ) 。 


IT 


94.1 Pelih 


Elastic 官 方 提供 各 种 语言 的 客户 端 库 ， 其 中 ，Perl 库 提供 了 对 


use Search: :Elasticsearch; 

= Search: :Elasticsearch-»new ( 
nodes => ['192.168.0.2:9200']) ; 

my $bulk = $es-»bulk helper ( 

=> 'new index',) ; 


my $es 


index 


$bulk-»reindex ( 
source 

index 
size 


search type => 'scan' 


$ 


=> { 


=> 'old index', 


H 


他 工具 


=> 500, # default 


# default 


了 。 本 节 介绍 两 个 常用 的 方法 一 一 自己 写 程序 和 用 Logstash。 


建 索引 比较 方便 的 写法 和 示例 。 通 过 cpanm Search: : Elasticsearch 命 令 安装 完 库 后， 使 用 以 下 程序 即 可 : 


94.2 ”用 Logstash 重 建 索引 


在 最 新 版 的 Logstash 中 ， 对 logstash-input-elasticsearch 插 件 做 了 一 定 的 修改 ， 使 得 通过 Logstash 完 


重建 索引 操作 的 Logstash 配 置 如 下 : 


建 索引 成 为 可 能 。 


input ( 


elasticsearch ( 
hosts => [ “192.168.0.2” ] 
port => "9200" 
index => "old index" 
size => 500 ` 
scroll => "5m" 
docinfo => true 


} 


output 


1 


elasticsearch { 
host => "192.168.0.2" 
port => “9200” 
protocol => “http” 


index => “%{[@metadata] [_index] }” 


index type => "$([Gmetadata][ typel]" 


document id => "$([&metadata][ id]) 


如 果 做 reindex 的 源 索 引 并 不 是 Logstash 记 录 的 内 容 ， 也 就 是 没有 @timestamp 和 @version 这 两 个 Logstash 字 段 ， 那 么 可 以 在 上 面 配置 中 添加 一 段 filter 配 置 ， 确 保 前 后 索引 字段 完全 一 致 : 


filter 
mutati 


remove field => [ 


} 
} 


f 


ef 


"Qtimestamp" , 


"Qversion' ] 


9.5 Spark Streaming 交 互 


Apache Spark 是 一 个 高 性 能 集群 计算 框架 ， 其 中 Spark Streaming 作 为 实时 批 处 理 组 件 ， 由 于 简单 易 上 手 的 特性 而 深 受 人 们 的 喜爱 。 在 es-hadoop 2.1.0 版 本 之 后 ， 也 新 增 了 对 Spark 的 支持 ， 使 得 结 
合 Elasticsearch 和 Spark 成 为 可 能 。 


目前 最 新 版 本 的 es-hadoop 是 2.1.0-Beta4。 安 装 如 下 : 


wget http: //d3kbcqa49mib13.cloudfront.net/spark-1.0.2-bin-cdh4.tgz 
wget http://download.elasticsearch.org/hadoop/elasticsearch-hadoop-2.1.0.Beta4.zip 


然后 通过 ADD JARS-http://www.hzcourse.com/resource/readBook?path -/openresources/teach ebook/uncompressed/15426/OEBPS/Text/. /elasticsearch-hadoop- 
2.1.0.Beta4/dist/elasticsearch-spark_2.10-2.1.0.Beta4.jar 环 境 变 量 ， 把 对 应 的 jar 包 加 入 Spark 的 jar 环 境 中 。 


下 面 是 一 段 使 


import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 


org 
org 
org 
org 
org 
org 
org 
org 
org 
org 
org 


.apache.spark. _ 


spark streaming 接 收 kafka 消 息 队 列 ， 然 后 写 入 Elasticsearch 的 配置 : 


.apache.spark.streaming.kafka.KafkaUtils 


.apache.spark.streaming. 


.apache.spark.streaming.StreamingContext. 


.apache.spark.SparkContext 


.apache.spark.SparkContext. _ 


.apache.spark.SparkConf 
.apache.spark.sql. | 
.elasticsearch.spark.sql. 


.apache.spark.storage.Storagelevel 


.apache.spark.Logging 


import org.apache.log4j.(Level, Logger) 
object Elastic ( 
def main (args: Array[String]) { 
val numThreads - 1 


val zookeeperQuorum = "localhost:2181" 

val groupld - "test" 

val topic = Array ( “test” ) . map ( ( , numThreads) ) . toMap 
val elasticResource = “apps/blog” 


val sc - new SparkConf () 
.setMaster ( "local[*]" ) 
.setAppName ( "Elastic Search Indexer App” ) 
Sc.set ( "es.index.auto.create" , "true" 
val ssc = new StreamingContext (sc, Seconds (10) ) 
ssc.checkpoint ( "checkpoint" ) 
val logs = KafkaUtils.createStream (ssc, 
zookeeperQuorum, 
groupId, 
topic, 
StorageLevel.MEMORY AND DISK SER) 
map ( . 2) 
logs.foreachRDD ( rdd => ^ 
val sc - rdd.context 
val sqlContext = new SQLContext (sc) 
val log = sglContext.jsonRDD (rdd) 
log.saveToEs (elasticResource) 
} 
ssc.start () 
ssc.awaitTermination () 


注意 ， 代 码 中 使 用 了 Spark SQL 提供 的 jsonRDD () 方法 ， 如 果 在 对 应 的 Kafka topic 里 的 数据 本 身 并 不 是 已 经 处 理 好 了 的 JSON 数 据 的 话 ， 还 需要 自己 写 额 外 的 处 理 函 数 ， 利 用 cast class 来 规范 数据 。 


第 10 章 ”性 能 优化 


Elasticsearch 作 为 一 个 开 箱 即 用 的 产品 ， 在 生产 环境 上 线 之 后 ， 却 并 不 一 定 还 能 保持 一 贯 的 性 能 和 稳定 。 如 何 根据 实际 情况 提高 服务 的 性 能 ， 有 很 多 技巧 。 本 章 将 从 以 下 几 方面 讲解 性 能 优化 的 方法 : 
bulk 提 交 、gateway 配 置 、 集 群 状态 维护 、 缓 存 、 字 段 数据 、curator 工 具 。 


10.1 bulk 提交 


在 第 8 章 ， 我 们 已 经 知道 Elasticsearch 的 数据 写 入 是 如 何 操作 的 了 。 喜 欢 自己 动手 的 读者 可 能 已 经 迫不及待 地 自己 写 了 程序 开始 往 Elasticsearch 里 写 数 据 做 测试 。 这 时 候 大 家 会 发 现 : 程序 的 运行 速度 非 
常 一 般 ， 即 使 Elasticsearch 服 务 运行 在 本 机 ， 一 秒 钟 大 概 也 就 能 写 入 几 百 条 数据 。 


这 种 速度 显然 不 是 Elasticsearch 的 极限 。 事 实 上 ， 每 条 数据 经 过 一 次 完整 的 HTTP POST 请 求 和 Elasticsearch indexing 是 一 种 极 大 的 性 能 浪费 ， 为 此 ，Elasticsearch 设 计 了 批量 提交 方式 。 在 数据 读 取 
方面 ， 叫 mget 接 口 ， 在 数据 变更 方面 ， 叫 bulk 接 口 。mget 一 般 常 用 于 搜索 时 Elasticsearch 节 点 之 间 批 量 获取 中 间 结 果 集 ， 对 于 ELK stack 用 户 ， 更 常见 到 的 是 bulk 接 口 。 


bulk 接 口 采用 一 种 比较 简朴 的 数据 积累 格式 ， 示 例如 下 : 

# curl -XPOST http://127.0.0.1:9200/ bulk -d' 

( "create" : ( ^" index' : “test”, ^" type" : ‘typel” }} 

{ *fieldl' : (valuel' } 

( "delete" : ( “ index' : “test”, " type" : “typel” ) } 

( "index" : ( index” : “test”, ^" type" : ‘typel”, "id' : “1” }} 
{ *fieldl' : “value?” } T E 

{ “update” : ("id' : “I”, ^" type" : 'typel' , " index! : “test” ) ] 
{ *doc" : { “field2” : “value?” ) } ii 

' 


格式 是 ， 每 条 JSON 数 据 的 上 面 ， 加 一 行 描述 性 的 元 JSON ， 指 明 下 一 行 数据 的 操作 类 型 ， 归 属 索引 信息 等 。 


采用 这 种 格式 ， 而 不 是 一 般 的 JSON 数 组 格式 ， 是 因为 接收 到 bulk 请 求 的 Elasticsearch 节 点 ， 就 可 以 不 需要 做 完整 的 JSON 数 组 解析 处 理 ， 直 接 按 行 处 理 简短 的 元 JSON ， 就 可 以 确定 下 一 行 数据 JSON 转 
发 给 哪个 数据 节点 了 。 这 样 ， 一 个 固定 内 存 大 小 的 network buffer 空 间 ， 就 可 以 反复 使 用 ， 又 节省 了 大 量 JVM 的 GC。 


事实 上 ， 产 品级 的 Logstash、Rsyslog、Spark 都 是 默认 采用 bulk 接 口 进行 数据 写 入 的 。 对 于 打算 自己 写 程序 的 读者 ， 建 议 采 用 Per 的 Search: : Elasticsearch: : Bulk 或 者 Python 的 


elasticsearch.helpers.* 库 。 


10.1.1. bulk 大 小 


在 配置 bulk 数 据 的 时 候 ， 一 般 需 要 注意 的 就 是 请 求 体 大 小 (bulk size) 。 


这 里 有 一 点 细节 上 的 矛盾 ， 我 们 知道 ，HTTP 请 求 ， 是 可 以 通过 HTTP 状 态 码 100 Continue 来 持续 发 送 数据 的 。 但 对 于 Elasticsearch 节 点 接收 HTTP 请 求 体 的 Content-Length 来 说 ， 是 按照 整个 大 小 来 计 
算 的 。 所 以 ， 首 先 ， 要 确保 bulk 数 据 不 要 超过 http.max_content_length 设 置 。 


那么 ， 是 不 是 尽量 让 bulk size 接 近 这 个 数值 呢 ? 当然 不 是 。 依 然 是 请 求 体 的 问题 ， 因 为 请 求 体 需要 全 部 加 载 到 内 存 ， 而 JVM Heap 一 共 就 那么 多 ( 按 31GB 算 ) ， 过 大 的 请 求 体 ， 会 挤占 其 他 线程 池 的 空 
间 ， 反 而 导致 写 入 性 能 的 下 降 。 


再 考虑 网 卡 流量 ， 磁 盘 转 速 的 问题 ， 所 以 一 般 来 说， 建议 bulk 请 求 体 的 大 小 ， 在 15MB 左 右 ， 通 过 实际 测试 继续 向 上 探索 最 合适 的 设置 。 


Qus 


这 里 说 的 15MB 是 请 求 体 的 字 节 数 ， 而 不 是 程序 里 里 设置 的 bulk sizes. bulk size 一 般 指 数据 的 条 目 数 。 不 要 忘 了 ，bulk 请 求 体 中 ， 每 条 数据 还 会 额外 带 上 一 行 元 SON。 


以 Logstash 默 认 的 bulk_size= > 5000 为 例 ， 假 设 单条 数据 平均 大 小 200B， 一 次 bulk 请 求 体 的 大 小 就 是 1.5MB。 那 么 我 们 可 以 尝试 bulk_size= > 50000; 而 如 何 单条 数据 平均 大 小 是 20KB， 一 次 bulk 大 小 
就 是 100MB， 显 然 超 标 了 ， 需 要 兴 试 下 调 至 bulk_size=>500。 


10.1.2 UDP 方式 


Elasticsearch 其 实 还 提供 了 一 个 连 HTTP header 解 析 步 骤 都 能 省 略 的 bulk 方 法 ， 叫 UDP bulk， 即 开启 UDP 9700355 


接 nc 发 送 bulk 数 据 内 容 写 入 。 


由 于 UDP 的 不 可 靠 性 ，Elasticsearch 计 划 从 2.0 版 本 开始 废弃 该 功能 ， 确 实 需 要 高 性 能 写 入 又 不 担心 数据 缺失 问题 的 读者 ， 可 以 参考 Elasticsearch 官 方 文档 使 用 该 功能 。 


ur 
SG 


10.2 gateway 配置 


gateway 是 Elasticsearch 设 计 用 来 长 期 存储 索引 数据 的 接口 。 一 般 来 说 ， 大 家 都 是 用 本 地 磁盘 来 存储 索引 数据 ， 即 gateway.type 为 local。 


数据 恢复 中 ， 有 很 多 策略 调整 我 们 已 经 在 之 前 分 片 控制 小 节 讲 过 。 除 开 分 片 级 别 的 控制 以 外 ，gateway 级 别 也 还 有 一 些 可 优化 的 地 方 ， 如 下 所 示 : 


gateway.recover_after_nodes 参 数控 制 集 群 在 达到 多 少 个 节点 的 规模 后 ， 才 开始 数据 恢复 任务 。 这 样 可 以 避免 集群 自动 发 现 的 初期 ， 分 片 不 全 的 问题 。 
gateway.recover_after_time 参 数控 制 集群 在 达到 上 条 配置 设置 的 节点 规模 后 ， 再 等 待 多 久 才 开 始 数 据 恢复 任务 。 


- gateway.expected_nodes 参 数 设置 集群 的 预期 节点 总 数 。 在 达到 这 个 总 数 后 ， 即 认为 集群 节点 已 经 完全 加 载 ， 即 可 开始 数据 恢复 ， 不 用 再 等 待 上 条 设置 的 时 间 。 


共享 存储 上 的 影子 副本 


里 然 Elasticsearch 对 gateway 使 用 NFS、iscsi 等 共享 存储 的 方式 极力 反对 ， 但 是 对 于 较 大 量 级 的 索引 的 副本 数据 ，Elasticsearch 从 1.5 版 本 开始 ， 还 是 提供 了 一 种 节约 成 本 又 不 特别 影响 性 能 的 方式 : 影 
子 副本 (shadow replica) 。 


首先 ， 需 要 在 集群 各 节点 的 elasticsearch.yml 中 开启 选项 : 


lode.enable custom paths: true 


同时 ， 确 保 各 节点 使 用 相同 的 路 径 挂 载 了 共享 存储 ， 且 目录 权限 为 Elasticsearch 进 程 用 户 可 读 可 写 。 


然后 ， 创 建 索引 : 


# curl -XPUT 'http://127.0.0.1:9200/my index' -d ' 
í 

"index" : ( 

"number of shards" : 1, 

"number of replicas" : 4, 

"data path" : "/var/data/my index" , 

"shadow replicas" : true 


针对 shadow replicas，Elasticsearch 节 点 不 会 做 实际 的 索引 操作 ， 而 是 单纯 地 每 次 flush 时 ， 把 segment 内 容 fsync 到 共享 存储 磁盘 上 。 然 后 refresh 让 其 他 节点 能 够 搜索 该 segment 内 容 。 所 
LÀ, shadow replicas 里 是 没有 translog 的 ， 对 于 还 没有 refresh 的 数据 ， 如 果 GET 获 取 请 求 传 到 shadow replicas 上 ， 是 查询 不 到 的 ， 请 求 会 自动 变 成 preference=_primary 模 式 ， 只 从 主 分 片上 获取 数据 。 
同 理 ， 在 cluster state 还 没 定期 更 新 过 来 之 前 ， 节 点 上 的 索引 映射 可 能 也 还 保持 着 自己 主 分 片 数据 的 样式 ， 不 会 因为 shadow replica 里 数据 样式 的 变动 发 生变 动 ， 搜 索 请 求 也 有 可 能 失败 。 


综 上 ，shadow replicas 只 是 一 个 在 某 些 特定 环境 下 有 用 的 方式 。 在 资源 允许 的 情况 下 ， 还 是 应 该 使 用 local gateway。 而 另外 采用 snapshot 接 口 来 完成 数据 长 期 备份 到 HDFS 或 其 他 共享 存储 的 需要 。 


10.3 ”集群 状态 维护 


我 们 都 知道 ，Elasticsearch 中 的 master 跟 一 般 MySQL、Hadoop 的 master 是 不 一 样 的 。 它 即 不 是 写 入 流量 的 唯一 入 口 ， 也 不 是 所 有 数据 的 元 信息 的 存放 地 点 。 所 以 ， 一 般 来 说 ，Elasticsearch 的 
master 节 点 负载 很 轻 ， 集 群 性 能 是 可 以 近似 认为 随 着 data 节 点 的 扩展 线性 提升 的 。 


但 是 ， 上 面 这 句 话 并 不 是 完全 正确 的 。Elasticsearch 中 有 一 件 事情 是 只 有 master 节 点 能 管理 的 ， 这 就 是 集群 状态 (cluster state) 。 


集群 状态 中 包括 以 下 信息 : 

:集群 层面 的 设置 。 

“ 集群 内 有 哪些 节点 。 

“ 各 索引 的 设置 、 映 射 、 分 析 器 和 别名 等 。 


: 索引 内 各 分 片 所 在 的 节点 位 置 。 


这 些 信 息 在 集群 的 任意 节点 上 都 存放 着 ， 你 也 可 以 通过 /_cluster/state 接 口 直接 读 取 到 其 内 容 。 注 意 这 最 后 一 项 信息 ， 之 前 我 们 已 经 讲 过 Elasticsearch 怎 么 通过 简单 地 取 余 知道 一 条 数据 放 在 哪个 分 片 
里 ， 加 上 现在 集群 状态 里 又 记载 了 分 片 在 哪个 节点 上 ， 那 么 ， 整 个 集群 里 ， 任 意 节 点 都 可 以 知道 一 条 数据 在 哪个 节点 上 存储 了 。 所 以 ， 数 据 读 写 才 可 以 发 送 给 集群 里 任意 节点 。 


至 于 修改 ， 则 只 能 由 master 节 点 完成 ! 显然 ， 集 群 状态 里 大 部 分 内 容 是 极 少 变动 的 ， 唯 独 有 一 样 除 外 一 一 索引 的 映射 。 因 为 Elasticsearch 的 schema-less 特 性 ， 我 们 可 以 任意 写 入 JSON 数 据 ， 所 以 索 
引 中 随时 可 能 增加 新 的 字段 。 这 个 时 候 ， 负 责 容纳 这 条 数据 的 主 分 片 所 在 的 节点 ， 会 暂停 写 入 操作 ， 将 字段 的 映射 结果 传递 给 master 节 点 ; master 节 点 合并 这 段 修改 到 集群 状态 里 ， 发 送 新 版 本 的 集群 状态 
到 集群 的 所 有 节点 上 。 然 后 写 入 操作 才 会 继续 。 一 般 来 说 ， 这 个 操作 是 在 一 二 十 毫秒 内 就 可 以 完成 ， 影 响 也 不 大 。 


但 是 也 有 一 些 情况 会 是 例外 ， 下 面 介绍 两 种 情况 。 


1. 批 量 新 索引 创建 


在 较 大 规模 的 ELK stack 应 用 场景 中 ， 这 是 比较 常见 的 一 个 情况 。 因 为 ELK stack 建 议 采用 日 期 时 间作 为 索引 的 划分 方式 ， 所 以 定时 (一般 是 每 天 ) ， 会 统一 产生 一 批 新 的 索引 。 而 前 面 已 经 讲 
过 ，Elasticsearch 的 集群 状态 每 次 更 新 都 是 阻塞 式 的 发 布 到 全 部 节点 上 以 后 ， 节 点 才能 继续 后 续 处 理 。 


这 就 意味 着 ， 如 果 在 集群 负载 较 高 的 时 候 ， 批 量 新 建新 索引 ， 可 能 会 有 一 个 显著 的 阻塞 时 间 ， 无 法 写 入 任何 数据 。 要 等 到 全 部 节点 同步 完成 集群 状态 以 后 ,数据 写 入 才能 恢复 。 


不 巧 的 是 ， 中 国 使 用 的 是 北京 时 间 ，UTC+0800。 也 就 是 说 ， 默 认 的 ELK stack 新 建 索引 时 间 是 在 早上 8 点 。 这 个 时 间 点 一 般 日 志 写 入 量 已 经 上 涨 到 一 定 水 平 了 (当然 ， 晚 上 0 点 的 量 其 实 也 不 低 ) 。 


对 此 ， 可 以 通过 定时 任务 ， 每 天 在 最 低谷 的 早上 三 四 点 ， 提 前 通过 POST mapping 的 方式 ， 创 建 好 之 后 几 天 的 索引 。 就 可 以 避免 这 个 问题 了 。 


2. 过 多 字段 持续 更 新 


这 是 另 一 种 常见 的 滥用 。 在 使 
个 Windex.do? uid=1234567890&action=payload” 的 URL 会 被 转换 成 如 下 JSON: 


ELK stack 处 理 访问 日 志 时 ， 为 了 查询 更 方便 ， 可 能 会 采用 logstash-filter-kv 揪 件 ， 将 访问 日 志 中 的 每 个 URL 参 数 ， 都 切 分 成 单独 的 字段 。 比 如 一 


“urlpath” “/index.do” , “urlargs” : { “uid” "1234567890" , "action" "payload" , 
H 
但 是 ， 因 为 集群 状态 是 存在 所 有 节点 的 内 存 里 的 ， 一 旦 URL 参 数 过 多 ，Elasticsearch 节 点 的 内 存 就 被 大 量 用 于 存储 字段 映射 内 容 。 这 是 一 个 极 大 的 浪费 。 如 果 磁 上 URL 参 数 的 键 内 容 本 身 一 直 在 变动 ， 


直接 撑 爆 Elasticsearch 内 存 都 是 有 可 能 的 ! 以 上 是 真实 发 生 的 事件 ， 开 发 人 员 莫 名 的 选择 将 一 个 UUID 结 果 作为 key 放 在 URL 参 数 里 。 直 接 导致 Elasticsearch 集 群 master 节 点 全 部 OOM。 


如 果 你 在 Elasticsearch 日 志 中 一 直 看 到 有 新 的 Updating mapping[logstash-2015.06.01] 字 样 出 现 的 话 ， 请 郑重 考虑 一 下 自己 是 不 是 用 的 上 如 此 细 分 的 字段 列表 吧 。 


好 ， 三 秒 钟 过 去 ， 如 果 你 确定 一 定 以 及 肯定 还 要 这 么 做 ， 下 面 是 一 个 变通 的 解决 办 法 。 


nested object 


"urlargs" : [ 
{ “key”: "uid' , “value” : “1234567890” }, 
{ “key” “action” , “value” “payload” }, 


] 


nested object 来 存放 URL 参 数 的 方法 稍微 复杂 ， 但 还 可 以 接受 。 单 从 JSON 数 据 层面 看 ， 新 方式 的 数 


居 结 构 如 下 : 


没 错 ， 看 起 来 就 是 一 个 数组 。 但 是 JSON 数 组 在 Elasticsearch 里 是 有 两 种 处 理 方式 的 。 


如 果 直 接 写 入 数组 ，Elasticsearch 在 实际 索引 过 程 中 ， 会 把 所 有 内 容 都 平 铺 开 ， 变 成 Arrays of Inner Objects。 整 条 数据 实际 类 似 这 样 的 结构 : 


{ “urlpath” : [ "/index.do' ], "urlargs.key' : [“uid”，“action”，… 


这 种 方式 最 大 的 问题 是 ， 当 你 采 
命中 。 


], “urlargs.value” 


: [ “1234567890” , "payload" , =] 


urlargs.key: "uid" AND urlargs.value: "0987654321 "语句 意图 搜索 一 个 uid=0987654321 的 请 求 时 ， 实 际 是 整个 URL 人 参数 中 任意 一 处 value 为 0987654321 的 ， 都 会 


要 想 达 到 正确 搜索 的 目的 ， 需 要 在 写 入 数据 之 前 ， 指 定 urlargs 字 段 的 映射 类 型 为 nested object。 命 令 如 下 : 


# curl -XPOST http://127.0.0.1:9200/10gstash-2015.06.01/ mapping -d '( "accesslog" 


properties 
"urlargs" : { 
"type" "nested" , 
"properties" 
“key” : ( “type” “string” , “index” “not analyzed” , “doc values” : true }, 
“value” : { “type” “string” , “index” "not analyzed' , "doc values" : true } 


这 样 ， 数 据 实际 是 类 似 这样 的 结构 : 


“urlpath” : [ "/index.do" ], 
' 
"urlargs.key" 


r 


: [ “uid” ], “urlargs.value” : [ “1234567890” ], 


: [ “action” ], “urlargs.value” : [ “payload” ], 


{ 
i 
d 
) ^ 
{ "urlargs.key" 
} 


当然 ，nested object 节 省 字段 映射 的 优势 对 应 的 是 它 在 使 用 的 复杂 。Query 和 Aggs 都 必须 使 
nested query 语 法 如 下 : 


4 curl -XPOST http://127.0.0.1:9200/10gstash-2015.06.01/accesslog/ search -d ' 
{ 


“query” : ( 
"bool : ( 
"must" : [ 
{ “match” : ( “urlpath” "/index.do" }}, 
{ 
nested” 
"path" "urlargs" , 
"query" : ( 
"pool" į 
“must” : [ 
{ “match” : ( "urlargs.key' : “uid” }}, 
{ “match” : ( “urlargs.value”: “1234567890” }} 


FFH 


专门 的 nested query 和 nested aggs 才 能 正确 读 取 到 它 。 


nested aggs 语 法 如 下 : 


# curl -XPOST http://127.0.0.1:9200/10gstash-2015.06.01/accesslog/ search -d ' 


"topnuid" : ( 


"urlargs" 


filter" : { 
"term : { 


"urlargs.key' : "uid", 


"urlargs.value" 


104 缓存 


Elasticsearch 内 针对 不 同 阶段 ， 设 计 有 不 同 的 缓存 ， 以 此 提升 数据 检索 时 的 响应 性 能 。 主 要 包括 节点 层面 的 filter cache 和 索引 


Elasticsearch 的 query DSL 分 为 query 和 filter 两 种 ， 很 多 检索 语法 是 同时 存在 query 和 filter 里 的 。 比 如 最 常 


首先 ， 要 明白 query 跟 filter 的 区 别 : 


“query 是 要 相关 性 评分 的 ，filter 不 要 ; 


' query 结 果 无 法 缓存 ，filter 可 以 。 


所 以 ， 选 择 也 就 出 来 了 : 


“ 全 文 搜索 、 评 分 排序 ， 使 用 query; 


"是非 过 滤 ， 精 确 匹 配 ， 使 用 filter。 


下 面 分 别 讲述 这 两 个 缓存 。 


10.4.1 filter 缓存 


上 面 做 对 比 时 ， 说 filter 能 


如 果 想 要 强制 开启 这 些 默认 没有 的 filter cache， 需 要 在 请 求 的 JSON 中 带 上 "cache": true 参 数 。 


检索 的 时 候 想 尽量 使 
这 样 的 请 求 : 


启 的 。 


filter cache， 但 是 Elasticsearch 接 


# curl -XGET http://127.0.0.1:9200/ search -d ' 


{ 


"query' : (. 
filtered : ( 
"filter" : ( 
"range" : ( 


f 
l 
E 


"Qtimestamp' : { “gte” : 


事实 上 ，Kibana 3 中 ， 就 大 量 使 


需要 注意 的 是 ，filter cache 是 节点 层面 的 缓存 设 : 


可 以 


10.4.2 shard query 缓 存 


Elasticsearch 还 有 另 一 个 索引 


m 
回 


这 里 可 以 把 这 个 过 程 再 细 化 一 下 。 
值 的 结果 ， 这 一 段 处 理 ， 叫 做 query 阶 段 ; 汇聚 到 这 份 结果 后 ， 按 照 分 值 排序 ， 得 到 一 个 全 集群 最 终 需 要 的 文档 jd， 上 
段 都 结束 后 才 返 回响 应 。 在 稍 后 的 E 


后 ， 完 成 数据 的 汇聚 处 理 再 返 | 


给 客户 端 。 


回 


缓存 query 不 能 ， 其 实 是 不 精确 的 。 默 认 情 况 下 ， 并 不 是 所 有 的 filter 都 能 上 
缓存 ，Elasticsearch 就 对 这 几 个 默认 开启 了 filter cache 功 能 。 而 更 复杂 的 一 些 比 如 geo、script 等 filter， 从 fielddata 数 扩 
而 像 and、not、or 这 几 个 关系 型 fiter， 也 是 不 


asticsearch 日 志 记录 章节 ， 


"now - ld / d" }} 


了 这 种 filtered query 语 法 。 


， 每 个 节点 上 所 有 数据 在 响应 请 求 时 ， 是 共 


CS 


缓存 。 常 


有 要 求 必须 传递 query 参 数 ， 这 时 人 息 ， 有 一 个 特殊 的 query， 叫 filtered query。 其 作 


的 term、prefix、range 等 。 那 么 ， 怎 么 选择 是 使 


层面 的 query cache。 


query 还 是 filter 呢 ? 


的 比如 term、terms、prefix、range、bool| 等 filter, 


其 过 滤 结 果 明 确 ， 也 容易 设 


是 在 query 中 使 


一 个 缓存 空间 的 。 当 空间 用 


indices.cache.filter.size 配 置 来 设置 这 个 缓存 空间 的 大 小 ， 默 认 是 JVM 堆 的 10%， 也 可 以 设置 一 个 绝对 值 。 


层面 的 缓存 ， 叫 shard query cache。 之 前 章节 中 说 过 ，Elasticsearch 集 群 的 任意 节点 都 可 以 接受 请 求 ， 它 会 


， 按 照 LRU 策 略 淘汰 掉 最 冷 的 数据 。 


Elasticsearch 对 请 求 的 处 理 过 程 ， 是 有 不 同类 型 的 ， 默 认 的 叫 query then_fetch。 在 这 种 情况 下 ， 各 数据 节点 处 理 检索 请 求 后 ， 返 回 
向 对 应 节点 发 送 一 次 文档 获取 请 求 ， 拿 到 文档 内 容 ， 这 一 段 处 理 ， 叫 做 fetch 阶 段 。 两 


我 们 可 以 看 到 Elasticsearch 对 这 两 个 阶段 ， 甚 至 都 有 分 别 的 慢 查 询 记录 。 


居 到 过 滤 结 果 还 需要 进行 一 系列 计算 的 ，Elasticsearch 默 认 是 不 开启 filter cache 的 。 


filter， 这 样 ， 我 们 就 可 以 实现 如 下 


自动 转发 给 数据 所 在 的 各 个 节点 ， 等 待 各 节点 把 各 自 的 结果 


的 ， 是 只 包含 文档 jd 和 相关 性 分 


此 外 ， 还 有 DFS_query then_fetch 类 型 ， 提 高 小 数据 量 时 的 精确 度 ; query and _fetch 类 型 在 有 了 明确 routing 时 可 以 省 略 一 个 数据 来 回 ;count 类 型 ， 在 不 关心 文档 内 容 只 需要 计数 时 省 略 fetch 阶 段 ， 


这 是 ELK stack 聚 合 统计 场景 最 常用 


回 到 query cache， 这 里 这 个 query， 就 是 处 理 过 程 中 query 阶 段 的 意思 。 各 个 节点 上 的 数 


根据 上 面 的 请 求 类 型 介绍 ， 显 然 ， 只 有 当 search_type=count 


TE, query cache 默 认 并 不 


启 。 因 为 query cachete} 


， 还 有 几 个 先决 条 件 : 


的 时 候 ， 这 个 query cache 才 能 起 到 作用 。 


的 类 型 scan 类 型 批量 获取 数据 省 略 query 阶 段 ， 在 reindex 时 就 是 使 用 这 种 类 型 。 


居 分 片 ， 会 在 处 理 完 query 阶 段 时 ， 将 得 到 


“ 分 片 数 据 不 再 变动 ， 也 就 是 对 当天 的 索引 是 无 效 的 《如果 refresh_interval 很 大 ， 那 么 在 这 个 间隔 内 倒 也 算 有 效 ) ; 


“使 用 了 “now” 


“ 缓存 的 键 是 请 求 的 整个 JSON 字 符 串 ， 整 个 字符 串 发 生 任何 字 节 变 


以 ELK stack 场 景 来 说 ，Kibana 里 几 了 
是 在 变动 的 。query cache 在 处 理 Kibana 发 出 的 请 求 时 ， 完 


语法 的 请 求 无 法 被 缓存 ， 因 为 这 个 是 要 即时 计算 的 ; 


动 ， 缓 存 都 无 效 。 


所 有 的 请 求 都 是 有 @timestamp 作 为 过 滤 条 件 的 ， 而 


无 用 。 所 以 ， 虽 然 官网 宣称 query cache 对 日 志 场 景 非常 有 用 ， 但 是 对 使 用 Kibana 的 一 般 


的 本 分 片 有 关 该 请 求 的 计数 值 ， 缓 存 起 来 。 


大 多 数 是 以 最 近 N 小 时 /分 钟 这 样 的 选项 ， 也 就 是 说 ， 页 面 每 次 刷新 ， 发 出 的 请 求 JSON 里 的 时 间 过 滤 部 分 都 
户 来 说 ， 完 全 没 法 体会 到 这 个 优势 。 


如 果 是 自己 写 程序 做 历史 统计 分 析 和 展示 的 ， 想 办 法 固化 时 间 过 滤 条 件 或 者 干脆 去 掉 这 个 条 件 ， 那 么 用 上 这 个 特性 还 是 不 错 的 。 要 对 某 个 索引 开启 query cache 的 话 ， 利 用 index settings 接 口 动态 调整 
即 可 : 


# curl -XPUT http://127.0.0.1:9200/10gstash-2015.06.23/ settings -d' 
{ '"index.cache.query.enable" : true 
' 


此 外 ， 还 可 以 针对 具体 某 个 请 求 单独 开启 : 


# curl 'http://127.0.0.1:9200/10gstash-2015.06.23/ search?search type-count&query | 
cache-true' -d' 


1 


"agas" : ( : 
"popular colors" : ( 
"terms" : 
“field” : "colors" 


f 
} 
y 


和 filter cache—fÉ, query cache 的 大 小 也 是 以 节点 级 别 控制 的 ， 配 置 项 名 为 indices.cache.query.size， 其 默认 值 为 19%。 


10.5 “字段 数据 


字段 数据 (fielddata) ， 在 Lucene 中 又 叫 uninverted index。 我 们 都 知道 ， 搜 索引 殉 会 使 用 倒 排 索引 (inverted index) 来 映射 单词 到 文档 的 ID 号 。 同 时 ， 为 了 提供 对 文档 内 容 的 聚合 ，Lucene 还 可 
以 在 运行 时 将 每 个 字段 的 单词 以 字典 序 排 成 另 一 个 uninverted index， 可 以 大 大 加 速 计算 性 能 。 


作为 一 个 加 速 性 能 的 方式 ，fielddata 当 然 是 被 全 部 加 载 在 内 存 的 时 候 最 为 有 效 。 这 也 是 Elasticsearch 默 认 的 运行 设置 。 但 是 ， 内 存 是 有 限 的 ， 所 以 Elasticsearch 同 时 也 需要 提供 对 fielddata 内 存 的 限额 
方式 ， 如 下 所 示 : 


:indices.fielddata.cache.size 节 点 用 于 fielddata 的 最 大 内 存 ， 如 果 fielddata 达 到 该 阔 值 ， 就 会 把 旧 数 据 交 换 出 去 。 该 参数 可 以 设置 百分比 或 者 绝对 值 。 默 认 设置 是 不 限制 ， 所 以 强烈 建议 设置 该 值 ， 比 如 


1096, 


“indices.fielddata.cache.expire 进 入 fielddata 内 存 中 的 数据 多 久 自 动 过 期 。 注 意 ， 因 为 Elasticsearch 的 fielddata 本 身 是 一 种 数据 结构 ， 而 不 是 简单 的 缓存 ， 所 以 过 期 删除 fielddata 是 一 个 非常 消耗 资源 的 操作 。 
Elasticsearch 官 方 在 文档 中 特意 说 明 ， 这 个 参数 绝对 绝对 不 要 设置 ! 


10.5.1 Circuit Breaker 


Elasticsearch 在 total、fielddata、request 三 个 层面 上 都 设计 有 Circuit Breaker 以 保护 进程 不 至 于 发 生 OOM 事 件 。 在 fielddata 层 面 ， 其 设置 为 : 


- indices.breaket.fielddata.limit 默 认 是 JVM 扒 内 存 大 小 的 60%。 注 意 ， 为 了 让 设置 正常 发 挥 作用 ， 如 果 之 前 设置 过 indices.fielddata.cache.size 的 ， 一 定 要 确保 indices.breaket.fielddatalimit 的 值 大 于 


indices.fielddata.cache.size 的 值 。 和 否则 的 话 ，fielddata 大 小 一 到 limit 准 值 就 报错 ， 就 永远 道 不 了 size 阀 值 ， 无 法 触发 对 旧 数 据 的 交换 任务 了 。 


10.5.2 doc-values 


但 是 相 比较 集群 庞大 的 数据 量 ， 内 存 本 身 是 远 远 不 够 的 。 为 了 解决 这 个 问题 ，Elasticsearch 引 入 了 另 一 个 特性 ， 可 以 对 精确 索引 的 字段 ， 指 定 fielddata 的 存储 方式 。 这 个 配置 > 项 叫 : doc values, 


所 谓 doc values， 其 实 就 是 在 Elasticsearch 将 数据 写 入 索引 的 时 候 ， 提 前 生成 好 fielddata 内 容 ， 并 记录 到 磁盘 上 。 因 为 fielddata 数 据 是 顺序 读 写 的 ， 所 以 即使 在 磁盘 上 ， 通 过 文件 系统 层 的 缓存 ， 也 可 
以 获得 相当 不 错 的 性 能 。 


注意 ， 因 为 doc values 是 在 数据 写 入 时 即 生成 内 容 ， 所 以 ， 它 只 能 应 用 在 精准 索引 的 字段 上 ， 因 为 索引 进程 没 法 知道 后 续 会 有 什么 分 词 > 器 生成 的 结果 。 所 以 ， 字 段 设置 应 该 是 这 样 : 


"myfieldname" : ( 
"type" : "string' , 
“index” : "not analyzed" , 
"doc values" : true 


} 


10.6 curator TL E 


如 果 经 过 之 前 章节 的 一 系列 优化 之 后 ， 数 据 确实 超过 了 集群 能 承载 的 能 力 ， 除 了 拆 分 集群 以 外 ， 最 后 就 只 剩 下 一 个 办 法 了 : 清除 废旧 索引 。 


为 了 更 加 方便 地 做 清除 数据 ， 合 并 segment、 备 份 恢复 等 管理 任务 ，Elasticsearch 在 提供 相关 API 的 同时 ， 另 外 准备 了 一 个 命令 行 工 具 ， 叫 curator。curator 是 Python 程序 ， 可 以 直接 通过 pypi 库 安 
装 : 


# pip install elasticsearch-curator 
Oza 


是 elasticsearch-curator 不 是 curator。PyPi 原 先 就 有 另 一 个 项 目 叫 这 个 名 字 。 


10.61 ”参数 介绍 


和 ELK stack 里 其 他 组 件 一 样 ，curator 也 是 被 Elastic.co 收 购 的 原 开源 社区 周边 。 收 编 之 后 同样 进行 了 一 次 重 构 ， 命 令 行 参数 从 单字 母 风格 改 成 了 长 单词 风格 。 新 版 本 的 curator 命 令 可 用 参数 如 下 : 


Usage: curator [OPTIONS] COMMAND [ARGS]: 


Options 包 括 : 


ost TEXT Elasticsearch host. 


* -url_prefix TEXT Elasticsearch http url prefix. 


* -port INTEGER Elasticsearch port. 


- use. ssl Connect to Elasticsearch through SSL. 


ttp. auth TEXT Use Basic Authentication ex: user: pass 
* timeout INTEGER Connection timeout in seconds. 

* -master-only Only operate on elected master node. 

* —-dry-run Do not perform any changes. 


* -debug Debug mode 


oglevel TEXT Log level 


ogfile TEXT log file 
* -logformat TEXT Log output format|[default | logstash]. 


* -version Show the version and exit. 


help Show this message and exit. 


Commands 包 括 : 


* alias Index Aliasing 


location Index Allocation 


z 


oom Disable bloom filter cache 


ose Close indices 


a 


* delete Delete indices or snapshots 


9 


en Open indices 


9 


timize Optimize Indices 


* replicas Replica Count Per-shard 


y 


iow Show indices or snapshots 


* snapshot Take snapshots of indices (Backup) 


针对 具体 的 Command， 还 可 以 继续 使 用 --help 查 看 该 子 命令 的 帮助 。 比 如 查看 close 子 命令 的 帮助 ， 输 入 curator close--help， 结 果 如 下 : 


Usage: curator close [OPTIONS] COMMAND [ARGS]… 
Close indices 
Options: 
--help Show this message and exit. 
Commands: 
indices Index selection. 


10.6.2 ”常用 示例 


在 使 用 1.4.0 以 上 版 本 的 Elasticsearch 前 提 下 ，curator 曾 经 主要 的 一 个 子 命令 bloom 已 经 不 再 需要 使 用 。 所 以 ， 目 前 最 常用 的 三 个 子 命令 ,分 别 是 close、delete 和 optimize， 示 例如 下 : 


curator --timeout 36000 --host 10.0.0.100 delete indices --older-than 5 --time- 


unit days --timestring '$Y.$m.$d' --prefix logstash-mweibo-nginx- 


curator --timeout 36000 --host 10.0.0.100 delete indices --older-than 10 --time- 


unit days --timestring '$Y.$m.$d' --prefix logstash-mweibo-client- --exclude 


logstash-mweibo-client-2015.05.11' 


curator --timeout 36000 --host 10.0.0.100 delete indices --older-than 30 --time 


-unit days --timestring '$Y.$m.$d' --regex '^logstash-mweibo-Nd*"' 

curator --timeout 36000 --host 10.0.0.100 close indices --older-than 7 --time- 
unit days --timestring '$Y.$m.$d' --prefix logstash- 

curator --timeout 36000 --host 10.0.0.100 optimize --max num segments 1 indices 
--older-than 1 --newer-than 7 --time-unit days --timestring '$Y.$m.$d' --prefix 
logstash- 


这 一 顿 任 务 ， 结 果 是 : logstash-mweibo-nginx-yyyy.mm.dd 索 引 保存 最 近 5 天 ，logstash-mweibo-client-yyyy.mm.dd 保 存 最 近 10 天 ， 


天 前 的 logstash-* 索 引 都 暂时 关闭 不 用 ; 最 后 对 所 有 非 当日 日 志 做 Segment 合并 优化 。 


第 11 章 “测试 和 扩展 方案 


和 做 任何 系统 的 运 维 工作 一 样 ， 对 Elasticsearch 系 统 ， 我 们 同样 需要 掌握 系统 的 性 能 基线 、 扩 


logstash-mweibo-yyyy.mm.dd 索 引 保存 最 近 30 天 ; 且 所 有 七 


展 能 力 和 方案 ， 乃 至 安全 管理 ， 等 等 。 本 章 讲 述 的 内 容 包括 : 测试 方案 ， 对 Elasticsearch 分 布 式 系统 的 性 


能 基线 测试 方案 设计 。 多 集群 互联 ， 在 单 集群 扩展 能 力 不 足 ， 或 者 场景 不 适宜 的 情况 下 ， 如 何 通过 tribe 节 点 同时 访问 不 同 集群 的 方法 。puppet-elasticsearch 模 块 的 使 用 ， 包 括 使 用 Puppet 配 置 管理 系统 ， 


快速 部 署 Elasticsearch 集 群 。 计 划 内 停机 升级 的 操作 流程 。Shield 权 限 管理 ，shield 的 基本 上 


法 。 别 名 的 应 


，Elasticsearch 中 的 alias 功 能 ， 索 引 的 无 颖 切换 和 按 业务 过 滤 别 名 都 是 日 常 非常 有 


的 功能 。 


11.1. 测试 方案 


在 体验 完 Elasticsearch 便 捷 的 操作 后 ， 下 一 步 一 定 会 碰 到 的 问题 是 : 数据 写 入 变 慢 了 ， 机 器 变 卡 了 ， 是 需 


优化 ， 某 个 参数 能 造成 什么 样 的 影响 ? 


而 Elasticsearch 集 群 性 能 ， 受 服务 器 硬件 、 数 据 结构 和 长 度 、 请 求 接口 


由 于 Elasticsearch 是 近乎 线性 扩展 的 分 布 式 系统 ， 所 以 对 上 述 需求 我 们 都 可 以 总 结 成 同一 个 测试 模式 : 


T 


和 线 上 集群 相同 的 数据 写 入 进行 压 测 。 


5) 持续 压 测 数 小 时 ， 使 


4) 观察 写 入 性 能 ， 或 者 运行 查询 请 求 观察 搜索 聚合 性 能 。 


测试 完成 后 ， 根 据 监控 系统 数据 ， 确 定单 分 片 的 性 能 拐点 


Ln 


和 线 上 集群 相同 硬件 配置 的 服务 器 搭建 一 个 音节 点 集群 。 


和 线 上 集群 相同 的 映射 创建 一 个 0 副本 ，1 分 片 的 测试 索引 。 


或 者 适合 自己 预期 值 的 临界 点 。 这 个 数据 ， 就 是 一 个 基准 数 


需要 注意 的 是 ， 测 试 是 以 分 片 为 单位 的 ， 在 实际 使 用 中 ， 


影响 。 也 就 是 说 ， 假 如 你 在 基准 测试 中 得 到 单机 写 入 性 能 在 10000eps， 那 么 开启 一 个 副本 后 所 能 达到 的 eps 就 只 有 5000 了 。 还 想 写 入 10000eps 的 话 ， 就 需要 加 一 倍 机 器 。 


监控 系统 记录 eps、requesttime、fielddata cache, GC count 等 关键 数据 。 


居 。 之 后 的 扩容 计划 ， 都 可 以 以 这 个 基准 和 


做 优化 呢 ? 还 是 需要 扩容 设备 了 ? 如 果 做 扩容 ， 索 引 的 分 片 和 副本 设置 多 少 才 合适 ”如 果 做 


复杂 度 等 各 种 环节 影响 颇 大 。 这 些 问 题 ， 都 需要 有 一 个 标准 的 测试 流程 给 出 答案 。 


TK 


位 进行 。 


为 主 分 片 和 副本 分 片 都 是 在 各 自 节点 做 indexing 和 merge 操 作 ， 需 要 消耗 同样 的 写 入 性 能 。 所 以 ， 实 际 集群 的 容量 预 估 中 ， 要 考虑 副本 数 的 


另外 ， 测 试 中 我 们 使 用 的 配置 都 尽量 贴 合 当前 现状 。 事 实 上 ， 很 多 配置 可 能 其 实 并 不 合理 。 在 确定 基准 线 并 开始 扩容 之 前 ， 还 是 要 认真 调节 配 
取 一 个 最 终 的 基准 值 。 
审核 请 求 ， 更 是 一 个 长 期 的 过 程 ， 就 像 DBA 永 远 需要 关注 慢 查 询 一 样 。Elasticsearch 的 慢 查询 请 求 处 理 ， 请 阅读 13.2.1 节 “性 能 日 志 ”。 


11.2 ”多 集群 互联 


当 Elasticsearch 集 群发 展 到 一 定 规模 ， 单 集群 不 足以 应 对 庞大 的 在 线索 引 量 级 ， 或 者 由 于 业务 隔离 需求 ， 都 有 可 能 划分 成 多 个 集群 。 这 时 候 ， 另 一 个 问题 就 出 来 了 : 可 能 


两 个 集群 里 ， 但 是 还 是 需要 一 起 使 
这 时 候 ， 就 要 


tribe 节 点 只 需要 提供 集群 自动 发 现 方 | 


E 


的 。 如 果 是 自己 写 程序 ， 当 然 可 以 初始 化 两 个 对 象 ， 分 别 连接 两 个 集群 ， 得 到 结果 集 后 再 自行 合并 。 但 是 如 果 
到 Elasticsearch 中 一 个 特殊 的 角色 : tribe 节 点 。 


的 配置 ， 连 接 上 多 个 集群 后 ， 对 外 提供 只 读 功能 。elasticsearch.ym| 配 置 示例 如 下 : 


， 审 核 请 求 使 


的 接口 是 否 最 优 ， 然 后 


中 有 一 部 分 数据 ， 被 分 割 在 
ELK stack，Kibana 可 不 支持 同时 连接 两 个 集群 地 址 ， 


tribe: 
1002: 
cluster.name: es1002 
discovery.zen.ping.timeout: 100s 


discovery.zen.ping.multicast.enabled: false 
[ *10.19.0.22" , *10.19.0.24" ,10.19.0.21 *] 


discovery.zen.ping.unicast.hosts: 
1003: 

cluster.name: es1003 

discovery.zen.ping.timeout: 100s 


discovery.zen.ping.multicast.enabled: false 
10.19.0.97 *, 


discovery.zen.ping.unicast.hosts: [" 
9 *," 10.19.0.100 *] 
blocks: 
write: true 
metadata: true 
on conflict: prefer 1003 


10.19.0.98 * 


" 10.19.0.9 


注意 这 里 的 on_conflict 设 置 ， 当 多 个 集群 内 ， 索 引 名 称 有 冲突 的 时 候 ，tribe 节 点 默认 会 把 请 求 轮 询 转发 到 各 个 集群 上 ， 这 显然 是 不 可 以 的 。 所 以 可 以 设置 一 个 优先 级 ， 在 索引 名 冲突 的 时 候 ， 偏 向 于 转 
发 给 某 一 个 集群 。 

以 tribe 配 置 启动 的 Elasticsearch 服 务 ， 其 日 志 输入 如 下 : 

2015-06-18 18:05:51,983] [INFO node Manslaughter] version[1.5.1], 

pid[12846], build[5e38401/2015-04-09T13:41:352] 

2015-06-18 18:05:51,984] [INFO node Manslaughter] initial-izing …… 

2015-06-18 18:05:51,990] [INFO plugins Manslaughter] loaded [], si 

tes [] 

2015-06-18 18:05:54,891] [INFO node Manslaughter/1003]version 

1.5.1], pid[12846], build[5e38401/2015-04-09T13:41:352] 

2015-06-18 18:05:54,891] [INFO node Manslaughter/1003] initia 

lizing =- 

2015-06-18 18:05:54,891] [INFO plugins Manslaughter/1003] loaded [], 

sites [] 

2015-06-18 18:05:55,654] [INFO node Manslaughter/1003] initia 

lized 

2015-06-18 18:05:55,655] [INFO node Manslaughter/1002] version[1. 

5.1], pid[12846], build[5e38401/2015-04-09T13:41:352 

2015-06-18 18:05:55,655] [INFO node Manslaughter/1002] initia 

lizing … 

2015-06-18 18:05:55,656] [INFO plugins Manslaughter/1002] loaded [], 

sites [] 

2015-06-18 18:05:56,275] [INFO node Manslaughter/1002] initialized 

2015-06-18 18:05:56,285] [INFO node Manslaughter] initialized 

2015-06-18 18: 56,286] [INFO node Manslaughter] starting :- 

2015-06-18 18:05:56,486] [INFO transport Manslaughter] bound address 

[inet[/0:0:0:0:0:0:0:0:9301]), publish address (inet /10.19.0.100:9301]) 

2015-06-18 18:05:56,499] [INFO discovery Manslaughter] elasticsearch/ 

Oewo-L2fR3y2xsgpsol40g 

2015-06-18 18:05:56,530] [INFO ] [node Manslaughter/1003] starting … 

2015-06-18 18:05:56,603] [INFO ] [transport Manslaughter/1003] bound 

address (inet[/0:0:0:0:0:0:0:0:9302]]), publish address (inet[/10.19.0.100:9302]) 

2015-06-18 18:05:56,609] [INFO ] [discovery Manslaughter/1003] es1003/ 

ml-cDaFTSoqqyC2iiQhECA 

2015-06-18 18:06:26,610] [INFO node Manslaughter/1003] started 

2015-06-18 18:06:26,611] [INFO node Manslaughter/1002] start 

ing = 

2015-06-18 18:06:26,674] [INFO ] [transport Manslaughter/1002] bound 

address (inet[/0:0:0:0:0:0:0:0:9303]), publish address (inet[/10.19.0.100:9303]) 

2015-06-18 18:06:26,676] [INFO ] [discovery Manslaughter/1002] es1002/ 


A4FPiRPh7TFyBk-BaPc TLg 

2015-06-18 18:06:56,677] [INFO node Manslaughter/1002] started 

2015-06-18 18:06:56,677] [INFO node Manslaughter] started 

2015-06-18 18:07:37,266] [INFO cluster.service Manslaughter/1003] detected 

master [10.19.0.97] [jnA-rt2fS 22Mz9nYl5Ueg] [localhost.localdomain] [inet[/10.19. 0.97:9300]] 

(max local storage nodes-1, data-false, master-true), added ([10.19.0.73][ S8ylzlOTv6NyplYoMRNGQ] [esnode073 .mweibo.bx.sinanode.com][inet[/10.19.0.73:9300]] (max local storage nc 
2015-06-18 18:07:37,382] [INFO ][tribe Manslaughter] [1003] adding T E iz: 
node [[10.19.0.73] [ S8ylz1O0Tv6NyplYoMRNGQ] [esnode073.mweibo.bx.sinanode.com][inet[/10.19.0.73:9300]](max local storage nodes-1l, tribe.name-1003, master-false]]- 
2015-06-18 18:07:37,393] [INFO ] [tribe Manslaughter] [1003] adding B 

index [logstash-mweibo-vip-2015.06.15]--- 
2015-06-18 18:08:07,316] [INFO cluster.service Manslaughter/1002] detected 

master [10.19.0.22] [6qyOh9EURUyO7RBC dXDow] [1ocalhost.localdomain [inet[/10.19.0.22:9300]] (max local storage nodes-1, master-true], added ([10.19.0.93] [gAk1Y08iSsSfif2vvu6Iyw][ 
2015-06-18 18:08:07,350] [INFO ][indices.breaker Manslaughter/1002] Updating 

settings parent: [PARENT, type-PARENT,limit-259489792/247.4mb,overhead-1.0], fielddata: [fieldDATA, type-MEMORY, limit-155693875/148.4mb,overhead-1.03], request: [REQUEST, type-MEN 
2015-06-18 18:08:07,353] [INFO tribe Manslaughter] [1002] adding 

node [[10.19.0.93] [gAk1Y08iSsSfif2vvu6Iyw] [localhost.localdomain] [inet[/10.19.0.93:9300]] (max local storage nodes-1, tribe.name-1002, master=false}]…… 

2015-06-18 18:08:07,358] [INFO tribe Manslaughter] [1002] adding 

index [test.yingjul-mweibo client downstream success-2015.06.07]…… 

2015-06-18 18:08:13,208] [DEBUG] [discovery.zen.publish ] [Manslaughter/1003] received 

cluster state version 782404 
2015-06-18 18:08:13,208] [DEBUG] [discovery.zen.publish ] [Manslaughter/1002] received 
cluster state version 782405 


从 日 志 中 加 粗 的 内 容 可 以 明显 看 到 ， 节 点 是 如 何 分 别 连接 上 两 个 集群 的 : 分 别 启动 两 个 子 节点 (Manslaughter/1002 和 Manslaughter/1003) ， 等 二 者 都 启动 后 ， 才 算 tribe 节 点 启动 完成 ; 然后 子 节 
点 各 自 连接 对 应 的 集群 ， 各 自 获 取 不 同 集群 的 节点 和 索引 列表 ， 分 别 响应 来 自 两 个 集群 的 zen 请 求 。 


最 后 ， 我 们 可 以 使 用 标准 的 RESTful 接 口 来 验证 一 下 : 


# curl 10.19.0.100:9201/_cat/indices?v 

health status index Pri rep 
docs.count docs.deleted store.size pri.store.size 

green open  test.yingjul-mweibo client downstream success-2015.06.07 20 1 


40692459 0 154.1gb 77gb 

green open  weibo-client-video-2015.06.19 5 4 
0 0 970b 575b 

green open  dpool-pc-weibo-2015.06.19 20 1 
0 0 3.7kb 2.2kb 

green open  logstash-video-2015.06.16 27 0 
149015413 0 13.4gb 13.4gb 


不 同 集群 的 索引 ， 都 可 以 通过 tribe node 访 问 到 了 。 


11.3 puppet-elasticsearch 模 块 的 使 用 


Elasticsearch 作 为 一 个 java 应 用 ， 本 身 的 部 署 已 经 非常 简单 了 。 不 过 作为 生产 环境 ， 还 是 有 必要 采用 一 些 更 标准 化 的 方式 进行 集群 的 管理 。Elasticsearch 官 方 提供 并 推荐 使 用 Puppet 方 式 部 署 和 管理 。 
其 Puppet 模 块 源码 地 址 见 : https://github.com/elastic/puppet-elasticsearch 


11.3.1 “安装 和 配置 示例 


和 其 他 标准 Puppet Module 一 样 ，puppet-elasticsearch 也 可 以 通过 Puppet Forge 直 接 安装 : 


# puppet module install elasticsearch-elasticsearch 


安装 好 Puppet 模 块 后 ， 就 可 以 使 用 了 。 模 块 提供 几 种 Puppet 资 源 ， 主 要 用 法 如 下 : 


class { 'elasticsearch': 
version => '1.5.2', 
config => ( 'cluster.name' => 'es1003' }, 
java install => true, 


elasticsearch::instance ( $fqdn: 
config => { 'node.name' => $fqdn ], 
init defaults => { 'ES USER' => 'elasticsearch', 'ES HEAP SIZE' => $memorysize 
> 64 ? '31g' : $memorysize / 2 }, 
datadir => [ '/datal/elasticsearch' ], 
} 
elasticsearch::template ( 'templatename': 
host => $::ipaddress, 
port => 9200, 
content => '( "template" : "*" , "settings" :( "number of replicas" :0}}' 
} 


11.3.2 ”配置 解释 


示例 中 展示 了 以 下 三 种 资源 。 


- class: 配置 具体 安装 的 Elasticsearch 软 件 版 本 ， 全 集群 公用 的 一 些 基础 配置 项 。 注 意 ，puppet-elasticsearch 模 块 默 认 并 不 负责 Java 的 安装 ， 它 只 是 调用 操作 系统 对 应 的 Yum，Apt 工 具 ， 而 elasticsearch.tpm 或 
者 elasticsearch.deb 本 身 没有 定义 其 他 依赖 (因为 java 版 本 太 多 了 ， 定 义 起 来 不 方便 ) 。 所 以 ， 如 果 依 然 要 走 puppet-elasticsearch 配 置 来 安装 Java 的 话 ， 需 要 额外 开启 java_install 选 项 。 该 选项 会 使 用 另 一 个 Puppet 
Module puppetlabs-java 来 安装 ， 默 认 安 装 的 是 jdk。 如 果 你 要 节省 空间 ， 可 以 再 加 一 行 java_backage 来 明确 指定 软件 全 名 。 


- instance: 配置 具体 单个 进程 实例 的 配置 。 其 中 config 和 init_defaults 选 项 在 class 和 instance 资 源 中 都 可 以 定义 ， 实 际 运行 时 ， 会 自动 做 一 次 合并 ， 当 然 ，instance 里 的 配置 优先 级 高 于 class 中 的 配置 。 此 外 ， 
最 重要 的 定义 是 数据 目录 的 位 置 。 有 多 快 磁盘 的 ， 可 以 在 这 里 定义 一 个 数组 。 


: template: 模板 是 Elasticsearch 创 建 索引 映射 和 设置 时 的 预定 义 方式 。 一 般 可 以 通过 在 config/templates/ 目 录 下 放置 JISON 文 件 ， 或 者 通过 RESTful API 上 传 配 置 两 种 方式 管理 。 而 这 里 ， 单 独 提供 了 
template 资 源 ， 通 过 Puppet 来 管理 模板 。content 选 项 中 直接 填 入 模板 内 容 ， 或 者 使 用 fe 选项 读 取 文件 均 可 。 


Jip} 


事实 上 ， 模 块 还 提供 了 plugin 和 script 资 源 管理 这 两 方面 的 内 容 。 考 虑 在 ELK 中 ， 二 者 用 的 不 是 很 多 ， 本 节 就 不 单独 介绍 了 。 想 了 解 的 读者 可 以 参考 官方 文档 。 


114 计划 内 停机 升级 的 操作 流程 


Elasticsearch 作 为 一 个 新 兴 项 目 ， 版 本 更 新 非常 快 。 而 且 每 次 版 本 更 新 都 或 多 或 少 带 有 一 


要 的 性 能 优化 、 稳 定性 提升 等 特性 。 可 以 说 ，Elasticsearch 集 群 的 版 本 升级 ， 是 目前 Elasticsearch 运 维 必 


然 要 做 的 一 项 工作 。 


按照 Elasticsearch 官 方 设计 ， 有 restart upgrade 和 rolling upgrade 两 种 可 选 的 升级 方式 。 对 于 1.0 版 本 以 上 的 用 户 ， 


但 是 ， 对 于 3 


要 负载 是 数据 写 入 的 ELK stack 场 景 来 说 ， 却 并 不 是 这 样 ! 


rolling upgrade 的 步骤 大 致 如 下 : 


1) 


2) 


3) 


暂停 分 片 分 配 。 


单 节点 下 线 升级 


开启 分 片 分 配 。 


B. 


4) 等 待 集群 状态 变 绿 后 继续 上 述 步骤 。 


实际 运行 中 ， 步 骤 2) fElasticsearch& 


推荐 采用 rolling upgreade 方 式 。 


需要 至 少 达 到 replica/2+ 1 个 分 片 完 成 才能 算 完 成 。 也 就 意味 着 你 所 有 索引 都 必须 至 少 有 1 个 以 上 副本 分 片 开启 。 


[EE 


E, RZATAR, ELTONEBE LERET 


完全 丧失 了 rolling 的 必要 性 。 


副本 ) 。 


居 可 靠 性 的 要 求 ， 大 家 普遍 减 小 了 副本 数量 ， 甚 至 直接 关 


其 次 ， 步 又 3) 中 的 Elasticsearch 分 片 均衡 过 程 中 ， 由 于 Elasticsearch 的 副本 分 片 数据 都 需要 从 主 分 片 通过 网 络 复制 


新 传输 一 次 ， 而 由 于 奸 


虎 副 本 复制 。 这 样 一 来 ， 


节点 从 restart 到 加 入 集群 ， 大 概要 100s 左 右 的 时 间 。 也 就 是 说 ， 这 100s 内 ， 该 节点 上 的 所 有 分 片 都 是 unassigned 状 态 。 而 按照 Elasticsearch 的 设计 ， 数 据 写 入 


整个 rolling upgrade 期间， 数据 写 入 就 会 受到 严重 影响 ， 


量 启 ， 新 升级 的 节点 上 的 分 片 肯 定 全 是 副本 分 片 ( 除 非 压根 没 


在 数据 量 较 大 的 情况 下 ， 这 个 步骤 耗 时 可 能 是 几 十 分 钟 甚 至 以 小 时 计 。 而 且 并 发 和 限 速 上 稍微 不 注意 ， 可 能 导致 分 片 均衡 的 带宽 直接 占 满 网 卡 ， 正 常 写 入 也 还 是 受到 影响 。 所 以 ， 对 于 写 入 压力 较 


大 ， 数 据 可 靠 性 要 求 偏 低 的 实时 日 志 场景 ， 依 然 建议 大 家 进行 主动 停机 式 的 restart upgrade, 


restart upgrade 的 步骤 如 下 : 


) 首先 适当 加 大 集群 的 数据 恢复 和 分 片 均 衡 并 发 度 以 及 磁盘 限 速 : 


# curl -XPUT http://127.0.0.1:9200/ cluster/settings -d '{ 
s1 


“persistent” 
"cluster" Sd 
"routing" 


3 Í 


"allocation" 
"disable allocation" : “false” , 


"cluster concurrent ; rebalance" $ 5" 
"node concurrent recoveries" * 
“enable” "ali" 


} 
} 
" 
"indices" 
" recovery" 


i i! 


t: d 


“concurrent | streams” i osC730* 4 
"max bytes per sec' : “2gb” 


} 
} 


). 


"transient" : ( 


2) 


"cluster" :d 
"routing" 


s i 


"allocation" HET 
"all" 


"enable" 


暂停 分 片 分 配 : 


# curl -XPUT http://127.0.0.1:9200/ cluster/settings -d '( 
{ 


} 
p 


“transient” 


“cluster.routing.allocation.enable” : "none" 


3) 通过 配置 管理 工具 下 发 新 版 本 软件 包 。 


5) 


4) 公告 周知 后 ， 停 止 数据 写 入 进程 ( 即 Logstash indexer 等 ) 。 


如 果 使 用 Elasticsearch 1.6 版 本 以 上 ， 可 以 手动 运行 一 次 synced flush， 同 步 副 本 分 片 的 commit id， 缩 小 恢复 时 的 网 络 传输 带宽 : 


# curl -XPOST http://127.0.0.1:9200/ flush/synced 


6) 全 集群 统一 停止 进程 ， 更 新 软件 包 ， 重 新 启动 。 


7) 等 待 各 节点 都 加 入 到 集群 以 后 ， 恢 复 分 片 分 配 : 


# curl -XPUT http://127.0.0.1:9200/ cluster/settings -d '( 
: 人 


} 
p 


8) 
TAFA 


“transient” 
"cluster.routing.allocation.enable" : “all” 
由 于 同时 启 停 ， 主 分 片 几乎 可 以 同时 本 地 恢复 ， 整 个 集群 从 red 变 成 yellow 只 需要 2 分 钟 左右 。 而 


节点 恢复 的 耗 时 。 


后 的 副本 分 片 ， 如 果 有 synced flush， 同 样本 地 恢复 ， 否 则 网 络 恢 复 总 耗 时 ， 视 数据 大 小 而 定 ， 会 明 


9) 如 果 有 synced flush， 建 议 等 待 集群 变 成 green 状 态 后， 恢复 写 入 ; 否则 在 集群 变 成 yellow 状 态 之 后 ， 即 可 着 手 开始 恢复 数据 写 入 进程 。 


11:5 


Shield 权 限 管理 


Shield 是 Elastic 公 司 官方 发 布 的 权限 管理 产品 。 其 主要 特性 包括 : 

o 提供 集群 节点 身份 验证 和 集群 数据 访问 身份 验证 。 

:提供 基于 身份 角色 的 细 粒 度 资源 和 行为 访问 控制 ， 细 到 索引 级 别 的 读 写 控制 。 
“ 提供 节点 间 数 据 传输 通道 加 密 保护 输出 传输 安全 。 

“ 提供 审计 功能 。 


“ 以 插件 的 形式 发 布 。 


使 用 期 间 是 全 功能 的 。 过 期 后 Shield 将 会 在 降级 模式 下 工作 ， 此 模式 下 对 cluster health、cluster stats 以 及 index stats 等 接口 的 访问 将 被 阻止 无 法 使 


Shield 是 一 款 商业 产品 ， 不 过 提供 30 天 免费 试 


11.5.1. Shield 架构 


Shield 通 过 定义 一 套用 户 集合 来 认证 用 户 ， 采 用 抽象 的 域 方式 定义 用 户 集合 ,支持 : 
Shield 提供 工具 ./bin/shield/esusers 用 于 创建 和 管理 本 地 用 户 。 


“ 集成 LDAP 认 证 支持 映射 LDAP 安 全 组 到 Shield 角 色 ，LDAP 安 全 组 与 Shield 角 色 可 以 是 多 对 多 的 关系 。 


Shield 支 持 定义 多 个 认证 域 ， 采 用 order 字 段 进 行 优先 级 排序 。 如 一 个 本 地 域 esusers，order=1， 加 一 个 LDAP 域 ，order=2。 如 果 用 户 不 再 本 地 用 户 域 中 则 在 LDAP 域 中 查找 验证 。 其 中 : 


“ ./config/shield/roles.yml 文 件 定义 角色 和 角色 的 所 拥有 的 权限 。 
- ./config/shield/group_to_role_mapping.yml 文 件 定义 LDAP 组 到 角色 映射 关系 。 


shield 使 用 SSL/TLS 证 书 进行 相互 认证 和 通讯 加 密 。 加 密 是 可 选 配 置 ， 如 果 不 使 用 ，shield 节 点 之 间 可 以 进行 简单 的 密码 验证 (明文 传输 ) . 


Shield 采 用 RBAC 授 权 模型 ， 数 据 模型 包含 如 下 元 素 : 

“ 受 保 护 资源 (Secured Resource). : 控制 用 户 访问 的 客体 ， 包 括 cluster、index/alias 等 等 。 

* 权能 (Priviliege) : 用 户 可 以 对 受 保护 资源 执行 的 一 种 或 多 种 操作 ， 如 read、wtite 等 。 
:许可 (Permissions). : 对 被 保护 的 资源 拥有 的 一 个 或 多 个 权能 ， 如 read on the"products"index。 
: 角色 (Rol) : 命名 的 一 组 许可 。 


“ 用户 (Users) : 用 户 实体 ， 可 以 被 赋予 0 个 或 多 种 角色 ， 授 权 他 们 对 被 保护 的 资源 执行 各 种 权能 。 


shield 增 加 认证 尝试 、 授 权 失 败 等 安全 相关 事件 和 活动 日 志 。 


11.5.2 ”安装 部 署 


安装 License 和 Shield 揪 件 的 命令 如 下 : 


bin/plugin -i elasticsearch/license/latest 
bin/plugin -i elasticsearch/shield/latest 


注意 ， 初 次 运行 Shield 需 要 重新 启动 Elasticsearch 集 群 。 后 续 更 新 License (license.json 为 License 文 件 ) 就 可 以 在 线 运行 : 


# curl -XPUT -u admin 'http://127.0.0.1:9200/ licenses' -d (license.json 


然后 创建 本 地 管理 员 : 


./bin/shield/esusers useradd esadmin -r admin 


这 里 使 用 简单 的 配置 先 完成 基本 验证 : 使 用 纯 本 地 用 户 认 证 或 者 使 用 本 地 认证 + 基本 的 ldap 认 证 。 


1.Elasticsearch 配 置 


在 elasticsearch.yml 中 增加 如 下 配置 : 


hostname verification: false 
# shield.ssl.keystore.path:/app/elasticsearch/nodeOl.jks 
# shield.ssl.keystore.password:xxxxxx 


shield: 
authc: 
realms: 

default: 
type: esusers 
order: 1 

ldaprealm: 
type: ldap 
order: 2 
url: ^"ldap://ldap.example.com:389" 
bind dn: "uid-ldapuser, ou-users, o-services, dc-example, dc-com" 


bind password: changeme 
user search: 
base dn: "dc-example,dc-com" 
attribute: uid 
group search: 
base dn: "dc-example,dc-com" 
files: 
role mapping: "/app/elasticsearch/shield/group to role mapping.yml" 
unmapped groups as roles: false zd T 


2. 角 色 配 置 


根据 默认 配置 文件 增 减 角 色 和 访问 控制 权限 。 角 色 配 置 文件 可 以 在 线 修改 ， 保 存 后 立即 生效 : 


([INFO ][shield.authz.store ] [Winky Man] updated roles (roles file [/opt/elasticsea 


config/shield/roles.yml] changed) ) 


户 角色 也 需要 有 访问 “.kibana” 索 引 的 访问 权限 和 cluster: 


注意 ， 如 果 需 要 集成 Kibana 认 证 ， 


无 法 访问 到 数据 索引 。 
3. 用 户 组 与 角色 映射 配置 
根据 默认 配置 文件 增 减 用 户 、 用 户 组 与 角色 配置 中 定义 角色 的 映射 关系 ， 可 以 灵活 实现 各 种 需求 。 


INFO ][shield.authc.ldap.support] [Vishanti] role mappings file [/opt/ 
elasticsearch/config/shield/group to role mapping.yml] changed for realm [ldal 
ldaprealm]. updating mappings…) 


rch/ 


户 通 过 Kibana 认 证 后 仍然 


体 参照 Kibana 4 角色 中 的 定义 ， 否 则 


monitor/nodes/info 的 访问 权限 ， 


LDAP 组 仅 支 持 安全 组 ， 不 支持 动态 组 。 这 个 配置 文件 可 以 在 线 修改 ,保存 后 立即 生效 : 


p/ 


测试 方法 如 下 : 


# curl -u username http://127.0.0.1:9200/ 


11.6_ 别 名 的 应 用 


在 真实 的 索引 


别名 (alias) 是 Elasticsearch 中 一 个 很 有 趣 的 功能 ， 对 别名 的 操作 ， 都 会 实际 作 
切换 等 场景 中 ， 别 名 都 非常 有 用 。 本 节 即 举例 说 明 别 名 的 应 用 。 


11.6.1 索引 更 名 时 的 无 颖 切换 


上 。 甚 至 可 以 一 个 别名 同时 指向 多 个 索引 ， 多 个 别名 指向 一 个 索引 ， 乃 至 带 着 过 滤 条 件 的 别名 。 在 无 颖 


分 三 和 


由 于 各 种 原因 ， 难 免 会 在 ELK stack 系 统 已 经 上 线 后 ， 碰 到 需要 变更 索引 名 称 的 需求 。 下 面 


1. 索 引 名 前 缀 更 换 


中 日 志 场 景 中 的 常见 可 能 ， 讲 解 如 何 利用 alias 功 能 来 完成 索引 更 名 时 的 无 颖 切换 : 


居 ， 现 在 要 


一 个 nginx 


比如 之 前 收集 的 只 有 apache-%{+yyyy.MM.dd)} 数 


这 个 变更 在 Logstash 上 非常 好 完成 ， 但 是 到 Kibana 3 上 ， 就 得 
而 Kibana 4 上 更 是 没 法 做 到 跨 索引 模式 的 请 求 。 所 以 ， 建 议 采 


如 下 步骤 来 完成 : 


1) 为 当前 索引 (假设 为 nginx-2015.07.28) 建 一 个 alias 叫 做 accesslog-2015.07.28， 之 前 索引 


4 curl -XPOST 'http://localhost:9200/ aliases' -d ' 
1 


"actions" [ 
{ “add? : { “index” "nginx-2015.07.28" , “alias” "accesslog-2015.07.28 
{ "add" : { “index” "nginx-2015.07.27" , “alias” "accesslog-2015.07.27 


] 
p 


志 ， 再 叫 这 个 名 字 不 太 合 适 了 ， 想 统一 改 成 accesslog-%{+yyyy.MM .dd}。 


E& Spi [apache-]YYYY.MM.dd, [accesslog-]YYYY.MM.DD, 而 且 moment.js 还 会 多 拼 出 来 一 些 实际 不 存在 的 索引 名 ， 也 是 一 种 浪 


全 部 类 似 操作 : 


")bh 
xd 


2) 然后 把 Kibana 中 把 dashboard 配 置 的 索引 名 改 成 [accesslog-]YYYY.MM.DD。 


一 | 
Ao 


面 的 index 配 置 改 成 accesslog-9%{+yyyy.MM.dd}， 重 


3) f&LogstashH 
2.reindex 时 的 无 颖 切换 


另 一 种 情况 ， 更 名 只 是 临时 性 的 ， 比 如 


注意 ，Elasticsearch 提 供 的 /_aliases 接 口 ， 是 原子 性 的 。 所 以 ， 同 一 次 接 


步骤 如 下 : 


问 都 改 走 新 的 别名 : 


1) 创建 一 个 别名 指向 原 有 索引 ， 所 有 访 


# curl -XPUT http://localhost:9200/10gstash-2015.07.28/ alias/tmp-2015.07.28 


因为 修改 革 个 mapping 设 置 ， 我 们 需要 对 原 有 数据 索引 做 一 次 reindex。reindex 肯 定 需要 改 个 新 名 字 ， 那 么 在 reindex 过 程 中 ， 如 何 保证 无 颖 呢 ? 


内 ， 我 们 完成 对 一 个 别名 的 修改 ， 对 外 界 是 透明 的 。 所 以 ， 假 设 你 现在 有 一 个 索引 叫 logstash-2015.07.28， 对 其 reindex 的 


2) 进行 reindex 操 作 ， 导 入 数据 到 new-2015.07.28。 步 骤 见 本 书 之 前 章节 内 容 。 


3) 切换 别名 : 


# curl -XPOST http://localhost:9200/ aliases -d ' 


[ 
"remove" : 
"add" : 


"actions" : 
1 
{ 
] 
p 


“tmp-2015.07.28” 
1 


"alias" : 


"logstash-2015.07.28" , 
"tmp-2015.07.28" 


"index' : 
"new-2015.07.28" , “alias” : 


“index” : 


{ 
{ 


Fle 


3. 索 引 名 后 缀 时 间 粒 度 变 更 


期 拆 分 ， 准 备 把 syslog-%{yyyy.MM.dd} 改 成 syslog-%{yyyy.MM}， 按 月 分 索引 。 


为 了 节省 cluster state 和 segment count， 我 们 可 能 会 觉得 一 些小 数据 量 的 索引 没 必要 按照 


这 个 时 候 ， 我 们 需要 跟 上 面 一 个 场景 完全 相反 的 别名 设计 。 操 作 步 又 如 下 : 


1) 创建 一 个 当前 月 份 的 新 索引 (假设 当前 为 2015.07.29， 保 存 5 天 ) ， 同 时 创建 之 后 一 个 数据 保存 周期 内 每 天 的 别名 指向 : 


# curl -XPOST 'http://localhost:9200/syslog-2015.07' -d@syslog-mapping.json 
# curl -XPOST 'http://localhost:9200/syslog-2015.08' -désyslog-mapping.json 


4 curl -XPOST 'http://localhost:9200/ aliases' -d ' 
{ 
“actions” [ 

{ *add" { “index "syslog-2015.07" , "alias" ^syslog-2015.07.30" ) }, 
{ "add" : ( “index "syslog-2015.07" , "alias" ^syslog-2015.07.31" ) }, 
{ "add" : ( “index ^syslog-2015.08" , "alias" ^syslog-2015.08.01" ) }, 
{ “add” : ( “index “syslog-2015.08” , “alias “syslog-2015.08.02” } }, 
1 “add” { “index "syslog-2015.08" , "alias" "syslog-2015.08.03" } } 


] 
p 


注意 ， 如 果 你 跟 我 一 样 不 巧 ， 当 前 数据 保存 周期 跨 月 了 ， 记 得 把 下 个 月 的 索引 也 进行 类 似 操作 。 


始 写 入 按 月 的 新 索引 。 


2) 当天 半夜 跨 天 的 时 候 ， 修 改 重启 Logstash 配 置 ， 


3) 等 到 你 最 后 一 个 实际 按 天 命名 的 索引 也 超过 保存 周期 被 删除 后 ， 修 改 Kibana 上 的 索引 模式 为 [syslog-]YYYY.MM。 


1 


pst 


6.2 ”限制 索引 数据 部 分 可 读 


一 般 来 说 ， 所 有 的 nginx 访 问 
个 办 法 : 


志 肯 定 是 存在 一 个 索引 里 的 。 但 是 各 个 业务 部 门 只 负责 自己 的 几 个 域名 ， 那 么 该 部 门 的 


己 域 名 下 的 


志 就 够 了 。 这 个 需求 通常 来 说 ， 有 两 


“ 在 Logstash 中 按 域名 切 分 索引 。 这 种 做 法 的 缺点 是 : Elasticsearch 的 cluster state 会 成 倍 的 增长 ， 对 集群 的 内 存 使 用 和 稳定 性 带 来 严重 威胁 。 


“ 在 Kibana 加 一 个 fltering 过 滤 条 件 。 这 种 做 法 的 缺点 是 : 这 个 关键 的 flter 和 其 他 所 有 filter 排 在 一 起 ， 很 容易 被 不 小 心 清除 ， 而 且 也 依然 是 暴露 了 其 他 数据 在 仪表 瘟 上 。 


使 


别名 ， 可 以 较 好 地 实现 这 个 需求 。 可 以 在 template 配 置 中 ， 对 每 一 个 域名 创建 一 个 带 有 filter 条 件 的 alias: 


# curl -XPOST 
# curl -XPOST 


'http: //1ocalhost:9200/sys10g-2015.07' 
'http: //1ocalhost:9200/sys10g-2015.08' 


-désyslog-mapping.;json 
-désyslog-mapping.;json 


4 curl -XPOST 'http://localhost:9200/ aliases' -d ' 
{ 
“actions” [ 
{ "add" { "index" “syslog-2015.07” , "alias" “syslog-2015.07.30” } }, 
{ “add” : { “index” “syslog-2015.07” , “alias” “syslog-2015.07.31” ) }, 
{ "add" : { “index” “syslog-2015.08” , “alias” ^syslog-2015.08.01" } }, 
{ "add" : { “index” “syslog-2015.08” , “alias” ^syslog-2015.08.02" } }, 
{ *add" { “index” "syslog-2015.08" , “alias” "syslog-2015.08.03" ) } 
] 
p 
注意 ， 这 里 使 用 了 一 个 {index} 语 法 ， 这 是 Elasticsearch 为 此 定制 的 小 功能 ， 代 表 当 前 索引 的 实际 名 称 。 也 就 是 说 ， 每 当 新 的 索引 (比如 nginx-2015.07.28) 生成 的 时 候 ， 同 时 会 有 nginx-2015.07.28- 


www.corp.com 和 nginx-2015.07.28-abc.corp.com 等 alias 指 向 nginx-2015.07.28。 而 在 对 这 些 别名 发 起 search、count、delete by query、MLT 等 请 求 的 时 候 ， 会 自动 带 上 各 自 的 filter 条 件 。 


这 样 在 Kibana 配 置 不 同业 务 的 仪表 盘 时 ， 就 可 以 直接 


alias 做 配置 了 。 


在 实际 使 


中 ， 可 能 还 需要 一 个 crontab 定 时 的 查询 是 否 有 新 的 域名 加 入 ， 自 动 对 新 域名 做 当天 的 alias， 并 把 它 加 入 template。 


第 12 章 “映射 与 模板 的 定制 


Elasticsearch 是 一 个 schema-less 的 系统 ， 但 并 不 代表 no schema， 而 是 会 尽量 根据 JSON 源 数据 的 基础 类 型 猜测 你 想 要 的 字段 类 型 映射 。 如 果 你 对 这 种 动态 生成 的 映射 关系 不 满意 ， 或 者 想 要 使 有 


一 些 


更 高 级 的 映射 设置 ， 那 么 就 需要 使 用 自 定义 映射 。 本 章 介绍 使 用 自 定义 映射 所 需 的 知识 ， 主 要 包括 : 映射 的 增删 改 查 的 基础 知识 ，Elasticsearch 的 核心 类 型 ， 自 定义 字段 映射 ， 特 殊 字段 ， 除 了 写 入 数据 字 
段 以 外 ， 会 自动 生成 的 一 些 特殊 字段 内 容 及 其 作用 ， 在 某 些 场 景 下 ， 会 需要 对 这 些 字段 的 映射 同样 做 定制 。 动 态 模板 映射 ， 可 以 在 定制 一 类 相似 的 字段 映射 时 起 到 灵活 简便 的 效果 。 索 引 模 板 ， 可 避免 每 天 
手动 创建 映射 的 重复 工作 。 

12.1 ”映射 的 增删 改 查 


正如 上 面 所 说 ，Elasticsearch 可 以 随时 根据 数据 中 的 新 字段 来 创建 新 的 映射 关系 。 所 以 ， 我 们 也 可 以 自己 在 还 没有 正式 数据 写 入 之 前 ， 先 创建 一 个 基础 的 映射 。 等 后 续 数 据 有 其 他 字段 
时 ，Elasticsearch 也 一 样 会 自动 处 理 。 


映射 的 创建 方式 如 下 : 


# curl -XPUT http://127.0.0.1:9200/10gstash-2015.06.20/ mapping -d ' 
{ 


“mappings” : { 


“syslog” : { 
“properties” : { 
"Qtimestamp' : { 
“type” "date" 
n 2 
message 
"type" "string" 
His 
pid 2 i 
"type" “long” 


注意 ， 对 于 已 存在 的 映射 ，Elasticsearch 的 自动 处 理 仅 限于 新 字段 出 现 。 已 经 生成 的 字段 映射 ， 是 不 可 变更 的 。 如 果 确 实 需 


而 如 果 是 新 增 一 个 字段 映射 的 更 新 ， 那 还 是 可 以 通过 /_mapping 接 口 直 接 完成 的 : 


， 请 参阅 之 前 9.4 节 reindex， 采 用 重新 导入 数 


居 的 方式 完成 。 


# curl -XPUT http://127.0.0.1:9200/10gstash-2015.06.21/ mapping/syslog -d ' 
{ 


“properties” : { 
“syslogtag” : { 
“type” "string' , 
"index" : "not analyzed" 


} 
p 


没 错 ， 这 里 只 需要 单独 写 这 个 新 字段 的 内 容 就 够 了 。Elasticsearch 会 自动 合并 进去 。 


虽然 写 入 数据 会 议 自动 添加 映射 ， 但 删除 数据 并 不 代表 会 删除 数据 的 映射 。 比 如 : 


# curl -XDELETE http://127.0.0.1:9200/10gstash-2015.06.21/syslog 


删除 了 索引 下 syslog 的 全 部 数据 ， 但 是 syslog 的 映射 还 在 。 删 除 映 射 (同时 也 就 删 掉 了 数据 ) 的 命令 是 : 


# curl -XDELETE http://127.0.0.1:9200/10gstash-2015.06.21/ mapping/syslog 


当然 ， 如 果 删 除 整个 索引 ， 那 映射 也 是 同时 被 清除 的 。 


学 习 索 引 映 射 最 直接 的 方式 ， 就 是 查看 已 有 数据 索引 的 映射 。 我 们 用 Logstash 写 入 Elasticsearch 的 数据 ， 都 会 根据 Logstash 自 带 的 template， 生 成 一 个 很 有 学 习 意 义 的 映射 。 查 看 已 有 了 映射 的 命令 如 


# curl -XGET http://127.0.0.1:9200/10gstash-2015.06.16/ mapping/logs 
{ 
“logstash-2015.06.16” : { 
“mappings” : { 
“logs” : { 
“properties” : { 
“etimestamp”: { 
"type" : “date” , 
“format” : "dateOptionalTime" 


host { 

"type" : “string” , 
“index” : “not analyzed” , 
"ignore above” : 256, 

"doc values" : true, 
“store” : false 

h x 

message : { 

"type" : “string” , 
“index” : “analyzed” , 


“omit_norms” : true 


1 
"Qversion" : { 


“index” : “not analyzed" , 
"doc values" : true, 
"type" : "string" 


12.2 ”Elasticsearch 的 核心 类 型 


本 节 介绍 Elasticsearch 自 带 的 数据 类 型 。 数 据 类 型 是 Lucene 索 引 的 依据 ， 也 是 我 们 做 手动 映射 调整 的 依据 。 


映射 中 主要 就 是 针对 字段 设置 类 型 以 及 类 型 相关 参数 。 那 么 ， 我 们 首先 来 了 解 一 下 Elasticsearch 支 持 的 核心 类 型 : 


JSON 基 础 类 型 如 下 : 


' 字符 串 : string 

“数字: byte, short, integer, long, float, double 
- 时间: date 

- 布尔 值 : true, false 
:数组 : array 

“对象: object 
Elasticsearch 独 有 类 型 如 下 : 
|: 多重: multi 

- 经 纬度 : geo, point 
网 络 地 址 : ip 

- MEAE SE: nested object 
二进制: binary 


“附件: attachment 


前 面 提 到 ，Elasticsearch 是 根据 收 到 的 JSON 数 据 里 的 类 型 来 猜测 的 。 所 以 ， 一 个 内 容 为 “123” 的 数据 ， 猜 测 出 来 的 类 型 应 该 是 string 而 不 是 long。 除 非 这 个 字段 已 经 有 了 确定 为 long 的 映射 关系 ， 那 
么 Elasticsearch 会 尝试 做 一 次 转换 。 如 果 转 换 失败 ， 这 条 数据 写 入 就 会 报错 。 


Qus 


Elasticsearch 的 映射 虽然 有 index 和 type 两 层 关系 ， 但 是 实际 索引 时 是 以 index 为 基础 的 。 如 果 同 一 个 index 下 不 同 type 的 字段 出 现 mapping 不 一 致 的 情况 ， 虽 然 数据 依然 可 以 成 功 写 入 并 生成 各 自 的 mapping， 但 
实际 fielddata 中 的 索引 结果 却 依然 是 以 index 内 第 一 个 mapping 类 型 来 生成 的 。 这 种 情况 下 可 能 会 有 比较 奇怪 的 事情 发 生 。 比 如 看 似 double 的 数据 实际 存储 成 long， 导 致 数值 比较 的 搜索 结果 异常 。 


从 Kibana 4 开始 ， 会 在 Object Setting 页 对 该 情况 做 出 冲突 预警 ; 并 预计 在 Elasticsearch 2.0 版 本 正式 拒绝 这 种 冲突 数据 写 入 。 


123 自 定 义 字 段 映射 


大 家 可 以 通过 之 前 12.1 节 展示 的 logstash-2015.06.16 映 射 发 现 ， 其 实 所 有 的 字段 都 有 好 几 个 属性 ， 这 些 都 是 我 们 可 以 自己 定义 修改 的 。 除 了 已 经 看 到 的 这 些 基本 内 容 外 ，Elasticsearch 还 支持 其 他 一 些 
可 能 会 比较 常用 的 映射 属性 : 


“ 全 文 索引 还 是 精确 索引 
- 自 定义 分 词 器 
“ 自 定义 日 期 格式 
12.3.1 ”精确 索引 
字段 都 有 几 个 基本 的 映射 选项 ， 类 型 (type) 和 索引 方式 (index) 。 以 字符 串 类 型 为 例 ，index 有 三 个 可 设置 项 : 
“ analyzed 默 认 选 项 ， 以 标准 的 全 文 索引 方式 ， 分 析 字 符 串 ， 完 成 索引 。 


:not_analyzed 精 确 索 引 ， 不 对 字符 串 做 分 析 ， 直 接 索 引 字 段 数据 的 精确 内 容 。 


“ no 不 索引 该 字段 。 


对 于 日 志 应 用 来 说 ， 很 多 字段 都 是 不 需要 在 Elasticsearch 里 做 解析 这 步 的， 所 以 ， 我 们 可 以 设置 : 


"myfieldname" : ( 
"type" : "string' , 
"index" : "not analyzed" 


} 


12.32 “时间 格式 


稍微 见 过 ELK stack 示 例 的 人 ， 都 对 其 中 @timestamp 字 段 的 特殊 格式 有 深刻 的 印象 。 这 个 时 间 格 式 在 Nginx 中 叫 $time iso8601， 在 Rsyslog 中 叫 date-rfc3339， 在 Elasticsearch 中 叫 
dateOptionalTime。 但 事实 上 ，Elasticsearch 完 全 可 以 接收 其 他 时 间 格 式 作为 时 间 字段 的 内 容 。 对 于 Elasticsearch 来 说 ， 时 间 字段 内 容 实际 都 是 转换 成 long 类 型 作为 内 部 存储 的 。 所 以 ， 接 收 段 的 时 间 格 
式 可 以 任意 配置 : 


"Qtimestamp' : ( “type” : “date” “index” : “not_analyzed” , "doc values” : true, “format” :  "dd/MMM/YYYY:HH:mm:ss Z” , 


而 Elasticsearch 默 认 的 时 间 字 段 格式 ， 除 了 dateOptionalTime 以 外 ， 还 有 一 种 ， 就 是 UNIX_MS， 毫 秒 级 的 UNIX 时 间 戳 。 因 为 这 个 数值 Elasticsearch 可 以 直接 好 不 修改 的 存 成 内 部 实际 的 long 数 值 。 


12.3.3 “多重 索引 


多 重 索引 是 Logstash 用 户 最 习惯 的 一 个 映射 ， 因 为 这 是 Logstash 默 认 设 置 开 启 的 配置 : 


title" : ( 
"type" : "string' , 
"fields" : ( 
"raw" : ( "type" : “string”, “index” : “not analyzed" } 


其 作用 是 ， 在 title 字 段 数据 写 入 的 时 候 ，Elasticsearch 会 自动 生成 两 个 字段 ， 分 别 是 title 和 title.raw。 这 样 ， 在 可 能 同时 需要 分 词 与 不 分 词 结果 的 环境 下 ， 就 可 以 很 灵活 的 使 用 不 同 的 索引 字段 了 。 比 
如 ， 查 看 标题 中 最 常用 的 单词 ， 应 该 使 用 title 字 段 ; 查看 阅读 数 最 多 的 文章 标题 ， 应 该 使 用 title.raw 字 段 。 


注意 ，raw 这 个 名 字 你 可 以 自己 随意 取 。 比 如 说 ， 如 果 你 绝 大 多 数 时 候 用 的 是 精确 索引 ， 那 么 你 完全 可 以 为 了 方便 反 过 来 定义 : 


"title" : ( 
"type" : “string” , 
“index” : "not analyzed" , 
"fields" : ( 
“alz”: ( "type" : "string" } 


} 
} 


124 ”特殊 字段 


上 面 介绍 的 都 是 对 普通 数据 字段 的 一 些 常 用 设置 。 而 实际 上 ，Elasticsearch 默 认 还 有 一 些 特殊 字段 ， 在 默默 地 发 挥 着 作用 。 这 些 字段 统一 以 _ 下 划 线 开头 。 在 之 前 9.1 节 中 ， 我 们 就 已 经 看 到 一 些 ， 比 如 
_index、_type、_id。 默 认 不 开启 的 还 有 _ttl、_timestamp、_size、_parent 等 。 这 里 需要 单独 介绍 两 个 ， 对 我 们 索引 和 检索 的 效果 和 性 能 都 有 较 大 影响 的 。 


1. all 


_al 里 存储 了 各 字段 的 数据 内 容 。 其 作用 是 ， 在 检索 的 时 候 ， 如 果 无 法 或 者 未 指明 具体 搜索 哪个 字段 的 数据 ， 那 么 Elasticsearch 默 认 就 会 是 从 _all 里 去 查找 。 


对 于 日 志 场 景 ， 如 果 你 的 日 志 划 分 出 来 的 字段 比较 少 上 数目 固定 。 那 么 ， 完 全 可 以 关闭 掉 all 功 能 ， 节 省 这 部 分 MO 和 CPU。 


" all' : ( "enabled" : false 


2. source 


_source 里 存储 了 该 条 记录 的 JSON 源 数据 内 容 。 这 部 分 内 容 只 是 按照 Elasticsearch 接 收 到 的 内 容 原样 存储 下 来 ， 并 不 经 过 索引 过 程 。 对 于 Elasticsearch 的 请 求 过 程 来 阅 ， 它 不 参与 Query 阶 段 ， 而 只 
于 Fetch 阶 段 。 我 们 在 GET 或 者 /_search 时 看 到 的 数据 内 容 ， 都 是 从 _source 里 获取 到 的 。 


所 以 ,虽然 source 也 重复 了 一 遍 索 引 中 的 数据 ， 一 般 我 们 并 不 建议 关闭 这 个 功能 。 因 为 一 旦 关闭 ， 你 搜索 的 结果 除了 一 个 id， 哈 都 看 不 到 。 对 于 日 志 场 景 ， 意 义 不 是 很 大 。 


当然 ， 也 有 少数 场景 是 可 以 关闭 _source 的 : 
“ 把 Elasticsearch 作 为 时 间 序 列 数据 库 使 用 ， 只 要 聚合 统计 结果 ， 不 要 源 数据 内 容 。 


* 把 Elasticsearch 作 为 纯 检索 工具 使 用 ，_id 对 应 的 内 容 在 HDFS 上 另外 存储 ， 搜 索 后 使 用 所 得 id 去 HDFS 上 读 取 内 容 。 


12.5 “动态 模板 映射 


不 想 使 用 默认 识别 的 结果 ， 单 独 设置 一 个 字段 的 映射 的 方法 ， 上 面 已 经 介绍 完毕 。 那 么 ， 如 果 你 有 一 类 相似 的 数据 字段 ， 想 要 统一 设置 其 映射 ， 就 可 以 用 到 下 一 项 功能 : 动态 模板 映射 


(dynamic templates) 。 


* default " : { 
"dynamic templates" : [ { 
"message field" : ( 
"mapping  : ( 
“index” : "analyzed" , 
"omit norms" : true, 
"store" : false, 
"type" : “string” 
1 
“match” : "*msg' , 
"match mapping type" : “string” 
} 
}, d 
"string fields" : { 
"mapping : ( 
“index” : "not analyzed” , 
"ignore above" ': 256, 
"store" : false, 
"doc values" : true, 
"type" : "string" 
), 
"match" bow" 
"match mapping type" : “string” 
} 
AL " 
properties td 


这 样 ， 只 要 字符 串 类 型 字段 名 以 msg 结 尾 的 ， 都 会 经 过 全 文 索 引 ， 其 他 字符 串 字段 则 进行 精确 索引 。 同 理 ， 还 可 以 继续 书写 其 他 类 型 的 match_mapping_type 和 match。 


12.6 索引 模板 


对 每 个 希望 自 定义 映射 的 索引 ， 都 要 定时 提前 通过 发 送 PUT 请 求 的 方式 创建 索引 的 话 ， 未 免 太 过 麻烦 。Elasticsearch 对 此 设计 了 索引 模板 功能 。 我 们 可 以 针对 同一 类 索引 ， 定 制 相同 的 模板 。 


模板 中 的 内 容 包括 两 大 类 ，setting (设置 ) 和 mapping (映射 ) 。setting 部 分 ， 多 为 在 elasticsearch.yml 中 可 以 设置 全 局 配置 的 部 分 ， 而 mapping 部 分 ， 则 是 这 节 之 前 介绍 的 内 容 。 


如 下 为 定义 所 有 以 te 开头 的 索引 的 模板 : 


# curl -XPUT http://localhost:9200/ template/template 1 -d ' 
{ 
"template" : “tex”， 
"settings" : { 
"number of shards' : 1 
), 
"mappings" : ( 
"typel' : ( 
" source" : ( "enabled" : false } 
} 
} 
p 


同时 ， 索 引 模 板 是 有 序 合并 的 。 如 果 我 们 在 同一 类 索引 里 ， 又 想 单独 修改 某 一 小 类 索引 的 一 两 处 单独 设置 ， 可 以 再 累加 一 层 模板 : 


# curl -XPUT http://localhost:9200/ template/template 2 -d ' 
{ 
"order" ; 1, 
"template" : 'tete*" , 
"settings" ( 
"number of shards' : 2 
b 
“mappings” : { 
“typel” : { 
“all” : ( “enabled” : false } 
i 
} 
p 


默认 的 order 是 0， 那 么 新 创建 的 order 为 1 的 template_2 在 合并 时 优先 级 大 于 template_1。 最 终 ， 对 tete*/type1 的 索引 模板 效果 相当 于 : 


{ 


"settings" : { 
"number of shards” : 2 
), 
"mappings" : ( 
"typel' : ( 


" source" : ( “enabled” : false }, 
“all” : ( “enabled” : false ) 
} 
} 
i 


Elasticsearch 作 为 一 个 分 布 式 系统 ， 监 控 功 能 自然 是 重 中 之 重 。Elasticsearch 本 身 提供 了 非常 完善 的 、 由 浅 及 深 的 各 种 性 能 数据 接口 。 与 数据 读 写 检索 接口 一 样 ， 采 用 RESTful 风 格 。 我 们 可 以 直接 使 
curl| 来 获取 数据 ， 编 写 监控 程序 ， 也 可 以 使 用 一 些 现成 的 监控 方案 。 通 常 这 些 方案 也 是 通过 接口 读 取 数据 ， 解 析 JSON， 泻 染 界面 。 


本 章 会 先 介 绍 一 些 常用 的 监控 接口 ， 及 其 响应 数据 的 含义 。 然 后 再 介绍 几 种 常用 的 开源 和 商业 Elasticsearch 监 控 产 品 ， 如 : 实时 bigdesk 方 案 ， 官 方 marvel 方 案 ，Zabbix trapper 方 案 。 


13.1 ”监控 相关 接口 


本 节 介绍 一 些 常用 的 监控 接口 ， 及 其 响应 数据 的 含义 。 


13.1.1 ”集群 健康 状态 


说 到 Elasticsearch 集 群 监控 ， 首 先 我 们 肯定 需要 一 个 总 体 意 义 上 的 概要 。 不 管 是 多 大 规模 的 集群 ， 告 诉 我 正常 还 是 不 正常 》 没 错 ， 集 群 健康 状态 接口 就 是 用 来 回答 这 个 问题 的 ， 而 且 这 个 接口 的 信息 出 
于 意料 地 丰富 。 


* curl -XGET 127.0.0.1:9200/ cluster/health?pretty 
{ "cluster name" :  "es1003" , "status" : “green” , "timed out” : false, "number of nodes” : 38, "number of data nodes' : 27, "active primary shards' : 1332, "active shards" 


} 


2. 状 态 信息 


输出 里 最 重要 的 就 是 status 这 行 代码 。 很 多 开源 的 Elasticsearch 监 控 脚 本 ， 其 实 就 是 拿 这 行 数据 做 报警 判断 。status 有 三 个 可 能 的 值 : 


green. (绿灯 ) ， 所 有 分 片 都 正确 运行 ， 集 群 非常 健康 。 


yellow ( 黄 灯 ) ， 所 有 主 分 片 都 正确 运行 ， 但 是 有 副本 分 片 缺 失 。 这 种 情况 意味 着 Elasticsearch 当 前 还 是 正常 运行 的 ， 但 是 有 一 定 风险 。 注 意 ， 在 Kibana 4 的 servet 端 启动 遇 辑 中 ， 即 使 是 黄 灯 状 
态 ，Kibana 4 也 会 拒绝 启动 ， 死 循环 等 待 集群 状态 变 成 绿灯 后 才能 继续 运行 。 


“ red (£p) ， 有 主 分 片 缺失 。 这 部 分 数据 完全 不 可 用 。 而 考虑 到 Elasticsearch 在 写 入 端 是 简单 的 取 余 算 法 ， 轮 到 这 个 分 片上 的 数据 也 会 持续 写 入 报错 。 
熟悉 Nagios 的 读者 ， 可 以 直接 将 这 个 红 黄 绿灯 对 应 上 Nagios 体 系 中 的 Critical、Warning、OK。 
3. 其 他 数据 解释 

: number of nodes， 集 群 内 的 总 节点 数 。 

- number of _data_nodes， 集 群 内 的 总 数据 节点 数 。 

“ active_primatry_shards， 集 群 内 所 有 索引 的 主 分 片 总 数 。 

:active_shards， 集 群 内 所 有 索引 的 分 片 总 数 。 

relocating shards， 正 在 迁移 中 的 分 片 数 。 
“initializing_shards， 正 在 初始 化 的 分 片 数 。 


- unassigned_shards ， 未 分 配 到 具体 节点 上 的 分 片 数 。 


显然 ， 后 面 三 项 在 正常 情况 下 ， 一 般 都 应 该 是 0。 但 是 如 果真 的 出 现 了 长 期 非 0 的 情况 ， 怎 么 才能 知道 这 些 长 期 未 分 配 或 者 正在 初始 化 的 分 片 影响 的 是 哪个 索引 呢 ? 本 书 随后 还 会 介绍 更 多 接口 获取 相关 
信息 。 不 过 在 集群 健康 这 层 ， 本 身 就 可 以 得 到 更 详细 一 点 的 内 容 了 。 


4.level 请 求 参数 


接口 请 求 的 时 候 ， 可 以 附加 一 个 level 参 数 ， 指 定 输出 信息 以 indices 还 是 shards 级 别 显 示 。 当 然 ， 一 般 来 说，indices 级 别 就 够 了 。 


* curl -XGET http://127.0.0.1:9200/ cluster/health?level-indices 
{ “cluster name" : “es1003” , "status" v “rd; "timed out' : false, "number of nodes" : 38, "number of o data 1 nodes" : 27, "active primary . shards" : 1332, "active shards" : 2380, 
Y; "1ogstash- 2015.05.30" : ( "status" : “red”， "number « of : shards”: 81, “number 。 of | replicas" :0,7 “active primary ， shards” : 80, "active | shards" : 80, "relocating : shards" 


, 


这 就 看 到 了 ， 是 logstash-2015.05.30 索 引 里 ， 有 一 个 分 片 一 直 未 能 成 功 分 配 ， 导 致 集群 状态 异常 的 。 


过 ， 一 般 来 说， 集群 健康 接口 还 是 只 用 来 简单 监控 一 下 集群 状态 是 否 正常 。 一 旦 收 到 异常 报警 ， 具 体 确 定 unassign shard 的 情况 ， 更 推荐 使 用 kopf 工 具 在 页 面 查看 。 


13.1.2 节点 状态 


TET 


集群 状态 是 从 最 上 层 高 度 来 评估 你 的 集群 概况 ， 而 节点 状态 则 更 底层 一 些 ， 会 返回 给 你 集群 里 每 个 节点 的 统计 信息 。 这 个 接口 的 信息 极为 丰富 ， 从 硬件 到 数据 到 线程 ， 应 有 尽 有 。 本 节 会 以 单 节点 为 
例 ， 分 段 介绍 各 部 分 数据 的 含义 。 


首先 ， 通 过 如 下 命令 获取 节点 状态 


* curl -XGET 127.0.0.1:9200/ nodes/stats 


1. 节 点 概要 

返回 数据 的 第 一 部 分 是 节点 概要 ， 主 要 就 是 节点 的 主机 和 名、 网卡 地 址 和 监听 端口 等 。 这 部 分 内 容 除了 极 少数 时 候 (一 个 主机 上 运行 了 多 个 Elasticsearch 节 点 ) 一 般 没有 太 大 用 途 : 

{ "cluster name" : “elasticsearch zach” , "nodes" : { "UNr6ZMf5Qk-YCPA L18BOQ' : { “timestamp” : 1408474151742, "name" : “Zach” , "transport address" : “inet[zacharys-air/192.16 
2. 索 引信 息 


这 部 分 内 容 会 列 出 该 节点 上 存储 的 所 有 索引 数据 的 状态 统计 ， 如 下 所 示 。 


1) 首先 是 概要 : 


"indices" : ( “docs” : { “count” : 6163666, "deleted" : 0 
), "store" : ( "size in bytes" : 2301398179, "throttle time in millis" : 122850 
l 


docs.count 是 节点 上 存储 的 数据 条 目 总 数 ; store.size_in_bytes 是 节点 上 存储 的 数据 占用 磁盘 的 实际 大 小 。 而 store.throttle time_in_millis 则 是 Elasticsearch 进 程 在 做 segment merge 时 出 现 磁盘 限 速 
的 时 长 。 如 果 你 在 Elasticsearch 的 日 志 里 经 常会 看 到 限 速 声明 ， 那 么 这 里 的 数值 也 会 偏 大 。 


2) 写 入 性 能 : 


“indexing” : ( “index total” : 803441, "index time in millis” : 367654, "index current” : 99, "delete _ total”: 0, "delete time in millis” : 0, "delete current" : 0 


b 


indexing.index total 是 一 个 递增 累计 数 ， 表 示 节 点 完成 的 数据 写 入 总 次 数 。 至 于 后 面 又 删除 了 多 少 ， 额 外 记录 在 indexing.delete total&, 


3) 读 取 性 能 : 


“get” : ( "total" : 6, "time in millis” : 2, "exists total' : 5, "exists time in millis”: 2, "missing total”: 1, "missing time in millis” : 0, “current” : 0 


get 这 里 显示 的 是 直接 使 用 id 读 取 数 据 的 状态 。 


4) 搜索 性 能 : 


“search” : { “open_contexts” : 0, "query total' : 123, "query time in millis” : 531, “query_current”: 0, "fetch total" : 3, "fetch time in millis” : 55, "fetch current" : 0 
) 


search.open_contexts 表 示 当 前 正在 进行 的 搜索 ， 而 search.query total 表 示 节 点 启动 以 来 完成 的 总 搜索 数 ，search.query time_in_millis 表 示 完 成 上 述 搜索 数 花费 时 间 的 总 和 。 显 
JA, query time in millis/query total 越 大 ， 说 明 搜索 性 能 越 差 ， 可 以 通过 Elasticsearch 的 slowlog， 获 取 具 体 的 搜索 语句 ， 做 出 针对 性 的 优化 。 


search.fetch_total 等 指标 含义 类 似 。 因 为 Elasticsearch 的 搜索 默认 是 query-then-fetch 式 的 ， 所 以 fetch 一 般 是 少 而 快 的 。 如 果 计 算出 来 search.fetch_time in millis» search.query time in millis, 
说 明 有 人 采用 了 较 大 的 size 参 数 做 分 页 查询 ， 通 过 slowlog 抓 到 具体 的 语句 ， 相 机 优化 成 scan 式 的 搜索 。 


5) 段 合 并 性 能 : 


“merges” : { “current” : 0, "current docs" : 0, "current size in bytes” : 0, “total” : 1128, "total time in millis” : 21338523, "total docs" : 7241313, "total size in bytes”: 572 
}, 


merges 数 据 分 为 两 部 分 ，current 开 头 的 是 当前 正在 发 生 的 段 合并 行为 统计 ;total 开 头 的 是 历史 总 计数 。 一 般 来 说 ， 作 为 ELK stack 应 用 ， 都 是 以 数据 写 入 压力 为 主 的 ，merges 相 关 数 据 会 比较 突出 。 


6) 过 滤器 缓存 : 


"filter cache" : ( "memory size in bytes" : 48, “evictions” : 0 


, 


filter cache.memory_size_in_bytes 表 示 过 滤器 缓存 使 用 的 内 存 ，filter_cache.evictions 表 示 因 内 存 满 被 回收 的 缓存 大 小 ， 这 个 数 如 果 较 大 ， 说 明 你 的 过 滤器 缓存 大 小 不 足 ， 或 者 过 滤器 本 身 不 太 适 合 
缓存 。 比 如 ， 在 ELK stack 场 景 中 常用 的 时 间 过 滤器 ， 如 果 使 用 @timestamp: ["now-1d"TO"now"] 这 种 表达 式 ， 需 要 每 次 计算 now 值 ， 这 样 一 来 就 无 法 长 期 缓存 。 事 实 上 ，Kibana 中 通过 timepicker 生 成 
的 filtered 请 求 里 ， 对 @timestamp 部 分 并 不 是 直接 使 用 “now”， 而 是 在 浏览 器 上 计算 成 毫秒 数值 ， 再 发 送 给 Elasticsearch。 


请 注意 ， 过 滤器 缓存 是 建立 在 segment 基 础 上 的 ， 在 当天 新 日 志 的 索引 中 ， 存 在 大 量 的 或 多 或 少 的 segment。 一 个 已 经 5GB 大 小 的 segment 和 一 个 刚刚 2MB 大 小 的 segment， 发 生 一 次 
filter cache.evictions 对 搜索 性 能 的 影响 区 别 是 巨大 的 。 但 是 节点 状态 中 本 身 这 个 计数 并 不 能 反应 这 点 区 别 。 所 以 ， 尽 力 减少 这 个 数值 ， 但 如 果 搜 索 本 身 感觉 不 慢 ， 那 么 有 几 个 也 无 所 谓 。 


7) id 缓存 : 


"id cache" : ( "memory size in bytes" : 0 


b 


id cachezparent/child mappings 使 用 的 内 存 。 不 过 在 ELK stack 场 景 中 ， 一 般 不 会 用 到 这 个 特性 ， 所 以 此 处 数据 应 该 一 直 是 0。 


8) fielddata: 


"fielddata" : ( "memory size in bytes" : 0, “evictions” : 0 


b 


此 处 显示 fielddata 使 用 的 内 存 大 小 。fielddata 用 来 做 聚合 、 排 序 等 工作 。 


Oza 


fielddata.evictions 应 该 永远 是 0。 一 旦 发 现 这 个 数据 大 于 0， 请 立刻 检查 自己 的 内 存 配置 、fielddata 限 制 ， 以 及 请 求 语句 。 
9) segments: 


"segments" : ( "count" : 319, "memory in bytes" : 65812120 


b 


segments.count 表 示 节 点 上 所 有 索引 的 segment 数 目的 总 和 。 一 般 来 说 ， 一 个 索引 通常 会 有 50~ 150 个 segment。 再 多 就 对 写 入 性 能 有 较 大 影响 了 (可 能 merge 速 度 跟 不 上 新 segment 出 现 的 速度 ) 。 
所 以 ， 请 根据 节点 上 的 索引 数据 正确 评估 节点 segment 的 情况 。 


segments.memory _in_bytes 表 示 segment 本 身 底层 数据 结构 所 使 用 的 内 存 大 小 。 像 索引 的 倒 排 表 、 词 典 、bloom filter (Elasticsearch1.4 以 后 已 经 默认 关闭 ) 等 ， 都 是 要 在 内 存 里 的 。 所 以 过 多 的 
segment 会 导致 这 个 数值 迅速 变 大 。 


3 .操作 系统 和 进程 信息 


操作 系统 信息 主要 包括 CPU、Loadavg、Memory 和 Swap 利 用 率 、 文 件 句 柄 等 。 这 些 内 容 都 是 常见 的 监控 项 ， 本 书 不 再 歼 述 。 


进程 ， 即 JVM 信 息 ， 主 要 在 于 GC 相关 数据 。 对 不 了 解 VM 的 GC 的 读者 ， 这 里 先 介绍 一 下 GC (垃圾 收集 ) 以 及 GC 对 Elasticsearch 的 影响 。 


Java 是 一 个 自动 垃圾 收集 的 编程 语言 ， 启 动 JVM 虚 拟 机 时 ， 会 分 配 到 固定 大 小 的 内 存 块 ， 这 个 块 叫 作 heap ( 堆 ) 。JVM 会 把 heap 分 成 两 个 组 : 


“Young 新 实例 化 的 对 象 所 分 配 的 空间 。 这 个 空间 一 般 来 说 只 有 100MB~500MB 大 小 。Young 空 间 又 分 为 两 个 survivor (幸存 ) 空间 。 当 Young 空 间 满 ， 就 会 发 生 一 次 young gc， 还 存活 的 对 象 ， 就 被 移入 幸 
存 空间 里 ， 已 失效 的 对 象 则 被 移 除 。 

“ Old 老 对 象 存 储 的 空间 。 这 些 对 象 应 该 是 长 期 存活 而 且 在 较 长 一 段 时 间 内 不 会 变化 的 内 容 。 这 个 空间 会 大 很 多 ， 就 Elasticsearch 来 说 ， 一 节点 上 可 能 就 有 30GB 内 存 是 这 个 空间 。 前 面 提 到 的 young gc 中 ， 
如 果 某 个 对 象 连续 多 次 幸存 下 来 ， 就 会 被 移 进 Old 空间 内 。 而 等 到 Old 空间 满 ， 就 会 发 生 一 次 old gc， 把 失效 对 象 移 除 。 


听 起 来 很 美好 的 样子 ， 但 是 这 些 都 是 有 代价 的 ! 在 GC 发 生 的 时 候 ，JVM 需 要 和 暂停 程序 运行 ， 以 便 自 己 追 踪 对 象 图 收集 全 部 失效 对 象 。 在 这 期 间 ， 其 他 一 切 都 不 会 继续 运行 。 请 求 没有 响应 ，ping 没 有 应 
答 ， 分 片 不 会 分 配 .…… 


当然 ，young gc 一 般 来 说 执行 极 快 ， 没 太 大 影响 。 但 是 old 空 间 那么 大 ， 稍 慢 一 点 的 gc 就 意味 着 程序 几 秒 乃至 十 几 秒 的 不 可 用 ， 这 太 危 险 了 。 


JVM 本 身 对 GC 算法 一 直 在 努力 优化 ，Elasticsearch 也 尽量 复 用 内 部 对 象 ， 复 用 网 络 缓冲 ， 同 时 还 提供 像 Doc Values 这 样 的 特性 。 但 不 管 怎么 说 ，GC 性 能 总 是 我 们 需要 密切 关注 的 数据 ， 因 为 它 是 集群 
稳定 性 最 大 的 影响 因子 。 


如 果 你 的 Elasticsearch 集 群 监控 里 发 现 经 常 有 很 耗 时 的 GC， 说 明 集 群 负载 很 重 ， 内 存 不 足 。 严 重 情况 下 ， 这 些 GC 导 致 节点 无 法 正确 响应 集群 之 间 的 ping， 可 能 就 直接 从 集群 里 退出 了 。 然后 数据 分 片 
也 随 之 在 集群 中 重新 迁移 ， 引 发 更 大 的 网 络 和 磁盘 |/O， 正 常 的 写 入 和 搜索 也 会 受到 影响 。 


在 节点 状态 数据 中 ， 以 下 部 分 就 是 VM 相关 的 数据 : 


“jvm” : ( "timestamp" : 1408556438203, "uptime in millis” : 14457, "mem" : { "heap used in bytes” : 457252160, "heap used percent” : 44, "heap committed in bytes" : 1038876672, “l 
) 


首先 可 以 看 到 的 就 是 堆 的 情况 。 其 中 这 个 heap_committed_in_bytes 指 的 是 实际 被 进程 使 用 的 内 存 ， 以 JVM 的 特性 ， 这 个 值 应 该 等 于 heap_max_in_bytes。heap_used_percent 则 是 一 个 更 直观 的 阔 值 
数据 。 当 这 个 数据 大 于 75% 时 ，Elasticsearch 就 要 开始 GC。 也 就 是 说 ， 如 果 节 点 的 这 个 数据 长 期 在 75% 以 上 ,说明 节点 内 存 不 足 ，GC 可 能 已 经 很 慢 了 。 更 进一步 ， 如 果 到 85% 或 者 95% 了 ， 估 计 节 点 一 次 
GC 能 耗 时 10s 以 上 ， 甚 至 可 能 会 发 生 OOM 了 。 


继续 看 下 一 段 代 码 : 


"pools" : ( "young" : ( “used in bytes” : 138467752, "max in bytes” : 279183360, "peak used in bytes" : 279183360, "peak max in bytes” : 279183360 
), “survivor” : { "used in bytes" : 34865152, "max in bytes” : 34865152, "peak used in bytes” : 34865152, "peak max in bytes” : 34865152 
), “old” : ( "used in bytes" : 283919256, "max in bytes” : 724828160, "peak used in bytes” : 283919256, "peak max in bytes” : 724828160 
} 


这 段 代 码 里 面 列 出 了 young、survivor 和 old GC 区 域 的 情况 ， 不 过 一 般 来 说 用 途 不 大 。 再 看 下 一 段 代码 : 


"gc" : ( "collectors" : { “young” : ( "collection count” : 13, "collection time in millis” : 923 
), “old” : ( “collection count" : 0, "collection time in millis” 
} 
} 


这 里 显示 的 young 和 old gc 的 计数 和 耗 时 。young gc 的 count 一 般 比较 大 ， 这 是 正常 情况 。old gc 的 count 应 该 就 保持 在 比较 小 的 状态 ， 包 括 耗 时 的 collection_time_in_millis 也 应 该 很 小 。 注 意 这 两 个 
计数 都 是 累计 的 ， 所 以 对 于 一 个 长 期 运行 的 系统 ， 不 能 拿 这 个 数值 直接 做 报警 的 判断 ， 应 该 是 取 两 次 节点 数据 的 差 值 。 有 了 差 值 之 后 ， 再 来 看 耗 时 的 问题 ， 一 般 来 说 ， 一 次 young gc 的 耗 时 应 该 在 
1~2ms, old gc 在 100ms 左 右 。 如 果 这 个 耗 时 有 量 级 上 的 差距 ， 建 议 打 开 slow-GC 日 志 ， 具 体 研究 原因 。 


4 线程 池 信息 


Elasticsearch 内 部 是 保持 着 几 个 线程 池 的 ， 不 同 的 工作 由 不 同 的 线程 池 负责 。 一 般 来 说， 每 个 池子 的 工作 线程 数 跟 你 的 CPU 核 数 一 样 。 之 前 有 传言 中 的 优化 配置 是 加 大 这 方面 的 配置 项 ， 其 实 没有 什么 
实际 帮助 一 一 能 干 活 的 CPU 就 那么 些 个 数 。 所 以 这 段 状 态 数据 目的 不 是 用 作 Elasticsearch 配 置 调 优 ， 而 是 作为 性 能 监控 ， 方 便 优 化 你 的 读 写 请 求 。 


Elasticsearch 在 index、bulk、search、get、merge 等 各 种 操作 都 有 专门 的 线程 池 ， 大 家 的 统计 数据 格式 都 是 类 似 的 : 


“index” : ( "threads" : 1, "queue" : 0, “active” : 0, “rejected” : 0, “largest” : 1, "completed" : 1 
} 


在 这 些 数据 中 ， 最 重要 的 是 rejected 数 据 。 当 线程 中 所 有 的 工作 线程 都 在 忙 ， 即 active= -threads, ARAARA EHANA, Büqueue»0. BERNE bA queuet EAA 
的 ， 默 认 是 100。 如 果 后 续 请 求 超过 100， 则 意味 着 Elasticsearch 无 法 接受 请 求 了 ， 它 会 拒绝 后 续 请 求 。 


dipl 


实 上 ， 集 群 的 承载 能 力 是 有 上 限 的 。 如 果 你 集群 每 秒 就 能 写 入 


如 果 你 发 现 你 的 Elasticsearch 服 务 返回 数据 中 有 rejected， 很 可 能 就 是 你 在 发 送 bulk 写 入 的 时 候 碰 到 HTTP 状 态 码 429 的 响应 报错 了 。 
10000 条 数据 ， 以 其 浪费 内 存 多 放 几 条 数据 在 排队 ， 还 不 如 直接 拒绝 掉 ， 至 少 可 以 让 你 知道 到 瓶颈 了 。 


另外 有 一 点 可 以 指出 的 是 ， 因 为 bulk queue 里 的 数据 是 维护 在 内 存 中 ， 所 以 节点 发 生意 外 死机 的 时 候 ， 是 会 丢失 的 。 


如 果 你 碰 到 bulk rejected， 可 以 尝试 以 下 步骤 : 
1) 暂停 所 有 的 写 入 进程 。 


2) 从 bulk 响 应 中 过 滤 出 来 rejected 的 那 部 分 。 因 为 bulk index 中 的 大 部 分 可 能 已 经 成 功 了 。 


3) 重 发 一 次 失败 的 请 求 。 


4) 恢复 写 入 进程 ， 或 者 重新 来 一 次 上 述 步骤 。 


大 家 可 能 看 出 来 了 ， 没 错 ， 对 rejected 其 实 压根 没什么 特殊 的 操作 ， 重 试 一 次 而 已 。 


当然 ， 如 果 这 个 rejected 是 持续 存在 并 增长 的 ， 那 重 试 也 无 济 于 事 。 你 可 能 需要 考虑 自己 的 集群 是 否 足以 支撑 当前 的 写 入 速度 要 求 。 


如 果 确 实 没 问题 ， 那 么 可 能 是 因为 客户 端 并 发 太 多 ， 超 过 集群 的 bulk threads 总 数 了 。 尝 试 减少 写 入 进程 的 个 数 ， 改 成 加 大 每 次 bulk 请 求 的 size。 


5. 文 件 系统 和 网 络 


数据 继续 往 下 走 ， 是 文件 系统 和 网 络 的 数据 。 文 件 系统 方面 ， 不 管 是 剩余 空间 还 是 |/O 数 据 ， 都 推荐 大 家 通过 更 传统 的 系统 层 监控 手段 来 完成 。 而 网 络 数据 方面 ， 主 要 有 两 部 分 内 容 : 


“transport” : { “ server | open" : 13, "rx count" : 11696, "rx size in bytes" : 1525774, "tx count" : 10282, "tx size in bytes" : 1440101928 
), "http' : ( "current open" : 4, "total opened" : 23 
) 


我 们 知道 Elasticsearch 同 时 运行 着 transport 和 http， 默 认 分 别 是 9300 端 口 和 9200 端 口 。 由 于 Elasticsearch 使 用 了 一 些 transport 连 接 来 维护 节点 内 部 关系 ， 所 以 transport.server open 正常 情况 下 一 直 
会 有 一 定 大 小 。 而 http.current_open 则 是 实际 连接 上 来 的 HTTP 客 户 端的 数量 ， 考 虑 到 HTTP 建 联 的 消耗 ， 强 烈 建 议 大 家 使 用 keep-alive 长 连接 的 客户 端 。 


6.Circuit Breaker 


继续 往 下 是 fielddata circuit breaker 的 数据 : 


"fielddata breaker”: ( “maximum size in bytes” : 623326003, "maximum size" : “594.4mb” , "estimated size in bytes" : 0, "estimated size" : “0b” , “overhead” : 1.03, “tripped” : 


fielddata_breaker.maximum _size 是 一 个 请 求 能 使 用 的 内 存 的 最 大 值 。fielddata_breaker.tripped 记 录 的 是 触发 circuit breaker 的 次 数 。 如 果 这 个 数值 太 高 ， 或 者 持续 增长 ， 说 明 目 前 Elasticsearch 收 
到 的 请 求 亟 待 优化 ， 或 者 单纯 的 ， 加 机 器 ， 加 内 存 。 


13.1.3 ”索引 状态 


索引 状态 监控 接口 的 输出 信息 和 节点 状态 监控 接口 非常 类 似 。 一 般 情况 下 ， 这 个 接口 单独 监控 起 来 的 意义 并 不 大 。 


不 过 在 Elasticsearch 最 新 的 1.6 版 中 ， 新 加 入 了 对 索引 分 片 级 别 的 commit id 功能 。 


回忆 一 下 之 前 原理 章节 的 内 容 ，commit 是 在 分 片 内 部 ， 对 每 个 Segment 做 的 。 而 数据 在 主 分 片 和 副本 分 片上 ， 是 由 各 自 节点 自行 做 segment merge 操 作 ， 所 以 副本 分 片 和 主 分 片 的 segment 的 
commit id 是 不 一 致 的 。 这 导致 Elasticsearch 副 本 恢复 时 ， 跟 主 分 片 比 对 commit id， 基 本 上 每 个 segment 都 不 一 样 ， 所 以 才 需 要 从 主 分 片 完整 重 传 一 份 数据 。 


新 加 入 分 片 级 别 的 commit id 后 ， 副 本 恢复 时 ， 先 比 对 跟 主 分 片 的 分 片 级 commit id， 如 果 一 致 ， 直 接 本 地 恢复 副本 分 片 内 容 即 可 。 
查看 分 片 级 别 commit id 的 命令 如 下 : 


# curl 'http://127.0.0.1: 1:9200/1ogstash -mweibo-2015.06.15/ stats/commit?level- 


shards&pretty'.- "indices : "logstash- 2015.06. 15" : dt “primaries” : {J}, “total” : ( ), “shards” : d TU Lt "routing" : ( "state" : “STARTED” , “primary” : t 
b. commit : dq “generation” : 726, "user data" : ( “translog id' : “1434297603053” , "sync id' : "AUALEh6wnBEGnOqcEXSS" 
Fs "num « docs" : 36792652 


) le 


为 了 节约 频繁 变更 的 资源 消耗 ，Elasticsearch 并 不 会 实时 更 新 分 片 级 commit id。 只 有 连续 5 分 钟 没有 新 数据 写 入 的 索引 ， 才 会 触发 给 索引 各 分 片 更 新 commit id 的 操作 。 如 果 你 查看 的 是 一 个 还 在 新 写 
入 数据 的 索引 ， 看 到 的 内 容 应 该 是 下 面 这 样 : 


“commit” : { “generation” : 590, “user data” : { “translog id” : “1434038402801” 
), "num docs" : 29051938 
J 


13314 ”等 待 执行 的 任务 


首先 需要 解释 的 是 ， 这 个 接口 返回 的 列表 ， 只 是 对 于 集群 的 master 节 点 来 说 的 等 待 执行 。 数 据 节 点 本 身 的 写 入 和 查询 线程 ， 如 果 因 为 较 慢 导 致 排队 ， 是 不 在 这 个 列表 里 的 。 


之 前 章节 已 经 讲 过 ，master 节 点 负责 处 理 的 任务 其 实 很 少 ， 只 有 集群 状态 的 数据 维护 。 所 以 绝 大 多 数 情况 下 ， 这 个 任务 列表 应 该 都 是 空 的 。 


# curl -XGET http://127.0.0.1:9200/_cluster/pending tasks 
{ “tasks” : [] 
l 


但 是 如 果 你 碰 上 集群 有 异常 ， 比 如 频繁 有 索引 映射 更 新 ， 数 据 恢 复 啊 ， 分 片 分 配 或 者 初始 化 的 时 候 反复 出 错 ， 就 会 看 到 一 些 任务 列表 了 : 


( "tasks" : [ ( "insert order”: 767003, "priority" : “URGENT”，“source”: “create-index [logstash-2015.06.01], cause [api]' , “time in queue millis” : 86, "time in queue 


可 以 看 到 列表 中 的 任务 都 有 各 自 的 优先 级 ，URGENT 优 先 于 HIGH。 然 后 是 任务 在 队列 中 的 排队 时 间 ， 任 务 的 具体 内 容 等 。 


在 上 例 中 ， 由 于 磁盘 文件 损坏 ， 一 个 分 片 中 某 个 segment 的 实际 内 容 和 长 度 对 不 上 ， 导 致 分 片 数据 恢复 无 法 正常 完成 ， 堵 塞 了 后 续 的 索引 映射 更 新 操作 。 这 个 错误 一 般 来 说 不 太 常见 ， 也 只 能 是 关闭 索 
或 者 放弃 这 部 分 数据 。 更 常见 的 可 能 是 集群 存储 长 期 数据 导致 索引 映射 数据 确实 大 到 了 master 节 点 内 存 不 足以 快速 处 理 的 地 步 。 
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这 时 候 ， 根 据 实际 情况 ， 可 以 有 以 下 几 种 选择 : 
“索引 就 是 特别 多 : 给 master 加 内 存 。 
“索引 里 字段 太 多 : 改 用 nested object 方 式 节省 字段 数量 。 


:索引 多 到 内 存 不 够 了 : 把 一 部 分 数据 拆 出 来 另 一 个 集群 。 


13.1.5 cat 接口 的 命令 行使 用 


之 前 介绍 的 各 种 接口 数据 ， 其 响应 数据 都 是 JSON 格 式 ， 更 适用 于 程序 处 理 。 对 于 我 们 日 常 运 维 ， 在 Linux 命 令 行 终端 环境 来 说 ， 和 简单 的 分 行 和 分 列表 格 才 是 更 方便 的 样式 。 为 此 ，Elasticsearch 提 供 了 
cat 接 口 。 


cat 接 口 可 以 读 取 各 种 监控 数据 ， 可 用 接口 列表 如 下 : 
- /. cat/allocation 

* /cat/shards 

- /. cat/shards/ {index} 

* / cat/ master 

: / cat/nodes 

* / cat/indices 

- [ cat/indices/ (index) 

* / cat/segments 

- / cat/segments/ {index} 
- / cat/count 

- / cat/count/ {index} 

“ [ cat/ recovery 

- /_cat/recovery/ {index} 
* /_cat/health 

- /_cat/pending tasks 

- /_cat/aliases 

- /_cat/aliases/ {alias} 

- /_cat/thread_pool 

- /_cat/plugins 

- /_cat/fielddata 

- /_cat/fielddata/ {fields} 


1. 集 群 状态 


还 是 以 最 基础 的 集群 状态 为 例 ， 采 用 cat 接 口 查 询 集群 状态 的 命令 如 下 : 


# curl -XGET http://127.0.0.1:9200/ cat/health 
1434300299 00:44:59 es1003 red 39 27 2589 1505 4100 


如 果 单 看 这 行 输出 ， 或 许 不 熟悉 的 用 户 会 有 些 茫然 。 可 以 通过 添加 参数， 输出 表 头 : 


# curl -XGET http://127.0.0.1:9200/ cat/health?v 


epoch timestamp cluster status node.total node.data shards pri relo init 

unassign pending tasks 
1434300334 00:45:34 26851003 green 39 27 2590 1506 5 0 0 0 
2. 节 点 状态 


# curl -XGET http://127.0.0.1:9200/ cat/nodes?v 


host ip heap.percent ram.percent load node.role master name 

esnodel09 10.19.0.109 62 69 6.37 d B 10.19.0.109 
esnode096 10.19.0.96 63 69 0.29 - a 10.19.0.96 
esnodel00 10.19.0.100 56 79 0.07 - m 10.19.0.100 


跟 集 群 状态 不 一 样 的 是 ， 节 点 状态 数据 太 多 ，cat 接 口 不 方便 在 一 行 表格 中 放下 所 有 数据 。 所 以 只 默认 返回 最 基本 的 内 存 和 负载 数据 
想 看 heap 百 分 比 和 最 大 值 : 


体 想 看 某 方面 的 数据 ， 也 是 通过 请 求 参数 的 方式 额外 指明 。 比 如 


# curl -XGET 'http://127.0.0.1:9200/ cat/nodes?v&h-ip, port, heapPercent, heapMax 
ip port heapPercent heapMax 
192.168.1.131 9300 66 25gb 


h 请 求 参数 可 用 的 值 ， 可 以 通过 ?help 请 求 参数 来 查询 : 


# curl -XGET http://127.0.0.1:9200/ cat/nodes?help 


id id,nodeld | unique node id 

host h host name 

ip i ip address 

port po bound transport port 
heap.percent hp, heapPercent used heap ratio 


ram.percent rp,ramPercent used machine memory ratio 
ram.max rm,ramMax total machine memory 
load 1 most recent load avg 


| 
| | 
| l 
I l 
| | 
heap.max | hm,heapMax | max configured heap 
| l 
| | 
| | 
node .role | r,role,dc,nodeRole | d:data node, c:client node… 


中 间 第 二 列 就 是 对 应 的 请 求 参数 的 值 及 其 缩写 。 也 就 是 说 以 上 示例 还 可 以 写成 : 


# curl -XGET http://127.0.0.1:9200/ cat/nodes?v&h-i, po, hp, hm 


3. 索 引 状 态 


查询 索引 列表 和 存储 的 数据 状态 是 也 是 cat 接 口 最 常用 的 功能 之 一 。 为 了 方便 阅读 ， 默 认输 出 时 会 把 数据 大 小 以 更 可 读 的 方式 自动 换算 成 合适 的 单位 ， 比 如 3.2tb 这 样 。 


如 果 你 打算 通过 shell 管 道 做 后 续 处 理 ， 那 么 可 以 加 上 bytes 参 数 ， 指 明 统 一 采用 字 节 数 输出 ， 这 样 保证 在 同一 个 级 别 上 排序 : 


# curl -XGET http://127.0.0.1:9200/ cat/indices?bytes-b | sort -rnk8 


green open logstash-mweibo-2015.06.12 26 1 754641614 0 2534955821580 
1256680767317 

green open logstash-mweibo-2015.06.14 271 855516794 0 2419569433696 
1222355996673 

4 分 片 状态 


# curl -XGET http://127.0.0.1:9200/ cat/shards?v 

index shard prirep state docs store ip node 
logstash-mweibo-h5view-2015.06.10 20 p STARTED 4690968 £679.2mb 127.0.0.1 10.19.0.108 
logstash-mweibo-h5view-2015.06.10 20 r STARTED 4690968 679.4mb 127.0.0.1 10.19.0.39 
logstash-mweibo-h5view-2015.06.10 2 p STARTED 4725961 684.3mb 127.0.0.1 10.19.0.53 
logstash-mweibo-h5view-2015.06.10 2 r STARTED 4725961 684.3mb 127.0.0.1 10.19.0.102 


同样 ， 可 以 用 help 查 询 其 他 可 用 数据 细节 。 比 如 每 个 分 片 的 segment.count: 


# curl -XGET 'http://127.0.0.1:9200/ cat/shards/logstash-mweibo-nginx-2015.06.14 
?vN&h-n, iic, sc' 


n iic sc 
10.19.0.72 0 42 
10.19.0.41 0 36 
10.19.0.104 032 
10.19.0.102 0 40 
5 .恢复 状态 


在 出 现 集群 状态 波动 时 ， 通 过 这 个 接口 查看 数据 迁移 和 恢复 速度 也 是 一 个 非常 有 用 的 功能 。 不 过 默认 输出 是 把 集群 历史 上 所 有 发 生 的 recovery 记 录 都 返回 出 来 ， 所 以 一 般 会 加 上 ?active_only 参 数 ， 仅 
列 出 当前 还 在 运行 的 恢复 状态 : 


4 curl -XGET 'http://127.0.0.1:9200/ cat/recovery?active only&v&h-i,s,shost,thost, 
fp,bp,tr,trp,trt' 

i s shost thost fp bp tr trp trt 

logstash-mweibo-2015.06.12 10 esnode041 esnode080 87.6% 35.3% 0 100.0% 0 

logstash-mweibo-2015.06.13 10 esnodel08 esnode080 95.5% 88.3% 0 100.0% 0 

logstash-mweibo-2015.06.14 17 esnodel02 esnode080 96.3% 92.5% 0 0.0% 118758 


6 线程 池 状 态 
curl -s -XGET http://127.0.0.1:9200/ cat/thread pool?v 
host ip bulk.active bulk.queue bulk.rejected index.active index. 
queue index.rejected search.active search.queue search.rejected 
esnode073 127.0.0.1 1 0 20669 0 
0 50 4 0 0 


包括 merge、optimize、flush 和 refresh 等 其 他 线程 池 状 态 ， 也 可 以 通过 h 参 数 指明 获取 。 


132 ”日 志 记录 


Elasticsearch 作 为 一 个 服务 ， 本 身 也 会 记录 很 多 日 志 信息 。 默 认 情 况 下 ， 日 志 都 放 在 4$ES_HOME/logs/ 目 录 里 。 


日 志 级 别 可 以 通过 elasticsearch.yml| 配 置 设置 ， 也 可 以 通过 /_cluster/settings 接 口 动态 调整 。 比 如 ， 如 果 你 的 节点 一 直 无 法 正确 地 加 入 集群 ， 你 可 以 将 集群 自动 发 现 方 面 的 日 志 级 别 修 改 成 DEBUG,， 来 
关注 这 方面 的 问题 : 


# curl -XPUT http://127.0.0.1:9200/ cluster/settings -d' 
{ “transient” : { '"logger.discovery  : “DEBUG” 
P i 


性 能 日 志 


除了 进程 状态 的 日 志 输出 ，Elasticsearch 还 支持 跟 性 能 相关 的 日 志 输出 。 针 对 数据 写 入 、 检 索 和 读 取 这 三 个 阶段 ， 都 可 以 设置 具体 的 慢 查询 阔 值 ， 以 及 不 同 的 输出 等 级 。 


此 外 ， 慢 查询 日 志 是 针对 索引 级 别 的 设置 。 除 了 在 elasticsearch.yml 中 设置 (注意 ， 默 认 是 全 注释 不 开启 的 状态 ) 以 及 通过 /_cluster/settings 接 口 配置 一 组 集群 各 索引 共用 的 参数 以 外 ， 还 可 以 针对 每 
个 索引 设置 不 同 的 参数 。 


比如 ， 我 们 可 以 先 设置 集群 共同 的 参数 : 


* curl -XPUT http://127.0.0.1:9200/ cluster/settings -d' a 
{ “transient” : { 'logger.index.search.slowlog' : “DEBUG” , “logger.index.indexing.slowlog” : “WARN” , “index.search.slowlog.threshold.query.debug” : “10s” , “index.search.: 
) 


p 


然后 针对 某 个 比较 大 的 索引 ， 调 高 设置 : 


# curl -XPUT http: /7121.0.0.1z 9200/1ogstash-wwwlog-2015. 06. 21/ settings -d' 
{ 'index.search.slowlog.threshold.query.warn" : “10s” , "index.search.slowlog.threshold.fetch.debug' : “500ms” , "index.indexing.slowlog.threshold.index.info' : “10s” 
} 


13.3 ”实时 bigdesk 方 案 


es 推荐 使 用 bigdesk 揪 件 ， 其 GitHub 地 址 为 : https://github.com/lukas-vicek/bigdesk。bigdesk 是 一 款 针对 Elasticsearch 性 能 的 开源 实时 监控 方案 ， 
本 节 会 着 重 介绍 其 中 最 重要 的 关注 区 域 。 


bigdesk 通 过 浏览 器 直 连 Elasticsearch 节 点 ， 发 起 RESTful 请 求 ， 并 泻 染 结果 成 图 。 所 以 其 安装 部 署 极其 简单 : 


# git clone https://github.com/lukas-vlcek/bigdesk 
4 cd bigdesk 

4 python -mSimpleHTTPServer 

Serving HTTP on 0.0.0.0 port 8000 =- 


通过 浏览 器 打开 http://localhost: 8000 即 可 看 到 bigdesk 页 面 。 在 endpoint 输 入 框 内 填写 要 连接 的 Elasticsearch 节 点 地 址 ， 选 择 refresh 间 隔 和 keep 时 长 ， 点 击 connect， 如 图 13-1 所 示 。 


127.0.0.1:8000/#nodes 


1 sec 


ES node REST endpoint Ihttp-//192.168.0.2:9200 Refresh ev V 2 sec 


图 13-1 bigdesk 设 置 项 
Oze 


设置 refresh 间 隔 请 考虑 ELK stack 使 用 的 template 里 实际 的 refresh_interval 是 多 少 ， 否 则 你 可 能 看 到 波动 太 大 的 数据 ， 不 足以 说 明 情 况 。 


点 选 某 个 节点 后 ， 就 可 以 看 到 该 节点 性 能 的 实时 走势 。 一 般 重 点 关注 JVM 性 能 和 索引 性 能 。 


有 关 JVM 部 分 的 截图 见 图 13-2。 


node REST endpoint ntp;//10.19.0.101:9200 Refresh every(2sc Ej Keep smnn history | 


Cluster: es1 003 I | | 

pil INO ci 10.19.0.100 |[10.19.0.101 |[10.19.0.102 | 10.19.0.103 |[ 10.19.0.104 | [10.19.0.165 || 10.19.0.106 || 10.19.0.107 || 10.19.0.108 
Status: yellow 10:19.0.109 | 10.19.0.39 ] 10.19.041 | [10.13.0.43 | [10.19.0.44 | A | 10-19:0.48 || 10-19.0.50][ 10.19.0.53 || 10.19.0.54 
10.19.0.64 |[ 10.19.0.55 [L019.0.66 10.19.0.67 10.19.0.68] 10.19.0.69 | 10.19.0.70 | 10.19.0.72 1019.073 [10.19.0774] 
101.075 || 10.19.0.76 |[ 0-19.0:77 | | 10.19.0.80] | 10.19.0.81][10.19.0.82][10.19.0.96 | [Rt 10.19.0.97 | [10.19.0.98 || 10.19.099] 


Selected node: 


Name: 10.19.0.45 

ID: hObi3kjxSia7 GABZ33oddw 

Hostname: esnode045.mweibo.bx.sinanode.com 
Elasticsearch version: 1.6.0 


JVM 


VM name: Java HotSpot(TM) 44-Bit Server VM Uptime: 5d 
VM vendor: Oracle Corporction Java version: 1.8.0 45 
VM version: 25.45-b02 PID: 32476 


Heap Mem Non-Heap Mem 


03:59 O4PM 040! 0402 : d 03:59 O4PM 040! 0402 


Committed: 25gb Committed: 112.3mb Peak: 222 Total time (O/Y): Oms / 2720?81ms 
Used: 20gb Used: 110.1mb Count: 172 Total count {O/Y): 0 / 35760 


Thread Pools 


03:59 04PM 040) 0£02 


Queue: 0 
Peak: 16 
Count: 0 


13-2 ”bigdesk 监 控 JVM 部 分 


有 关 数 据 读 写 性 能 部 分 的 截图 见 图 13-3。 


o Max as N 
o 


03:59 04 PM P 409 59 04 PM 0401 " 03:59 O4FM 04:01 04:02 04. 


Max: 32000 Total virtual: 576.1gb. "t weighted avg 5) Total: 1600% 
Open: 4017 Resident: 28.7gb Sys 11791 Process: 0% 
Shore: 1.1gb User totok 1805149 460ms 


HTTP & Transport 


HTIP address: Transcort address: 
inet(/10.19.0.45:9300] 

Bound address: 
Bound address: 

Pubish addrass: ingt[/0:0:0:0:0:0:0:0:0:9300] 
Publisn address: 
Inet[/10.19,0.45:9300] 


Indices 


Docs count: 2315178851 Rush: 33105, 3.7h 
Docs deleted: 0 Refresh: 139538, 5.8h 


Search requests per secood (A) Search time per second (A) 


D4 PM 1 0402 04/03 


Query: 1.8d 
Fetch; 3.7s 


Fiter: 787593 


图 13-3 bigdesk 监 控 io 部 分 


134 ”官方 marvel 方 案 


marvel 是 Elastic.co 公 司 推出 的 商业 监控 方案 ， 也 是 用 来 监控 Elasticsearch 集 群 实 时 、 历 史 状态 的 有 力 工具 ， 便 于 性 能 优化 以 及 故障 诊断 。 监 控 主要 分 为 六 个 层面 ， 分 别 是 集群 层 、 节 点 层 、 索 引 层 、 分 
片 层 、 事 件 层 、Sense， 如 下 所 示 。 


: 集群 层 : 主要 对 集群 健康 情况 进行 汇总 ， 包 括 集群 名 称 、 集 群 状态 、 节 点 数量 、 索 引 个 数 、 分 片 数 、 总 数据 量 、 集 群 版 本 等 信息 。 同 时 ， 对 节点 、 索 引 整 体 情况 分 别 展示 。 


“ 节点 层 : 主要 对 每 个 节点 的 CPU、 内 存 、 负 载 、 索 引 相关 的 性 能 数据 等 信息 进行 统计 ， 并 进行 图 形 化 展示 。 


DEA: 展示 的 信息 与 节点 层 类 似 ， 主 要 从 索引 的 角度 展示 。 

“ 分 片 层 : 从 索引 、 节 点 两 个 角度 展示 分 片 的 分 布 情 况 ， 并 提供 playback 功 能 演示 分 片 分 配 的 历史 过 程 。 
- 事件 层 : 展示 集群 相关 事件 ， 如 节点 脱离 、 加 入 ，Master 选 举 ， 索 引 创建 ，Shard 分 配 等 。 

“ Sense: 轻 量 级 的 开发 界面 ， 主 要 用 于 通过 API 查 询 数据 ， 管 理 集群 。 

Elastic.co 公 司 的 收费 标准 是 : 

“ 开发 模式 免费 。 

“ 生产 环境 前 5 个 节点 ， 每 年 1000 美 元 。 


“ 之 后 每 增加 5 个 节点 ， 每 年 加 收 250 美 元 。 


13.4.1 安装 和 印 载 


marve| 是 以 Elasticsearch 的 插件 形式 存在 的 ， 可 以 直接 通过 插件 安装 : 


4 ./bin/plugin -i elasticsearch/marvel/latest 


如 果 你 是 从 官网 下 载 的 安装 包 ， 则 运行 : 


# ./bin/plugin -i marvel -u file:///path/to/marvel-latest.zip 


各 节点 都 安装 完毕 后 ， 可 以 通过 下 行 命令 来 查看 节点 上 的 插件 列表 ， 检 查 列表 中 是 否 含有 marvel: 


# curl http://127.0.0.1:9200/ nodes/ local/plugins 


安装 之 后 ， 插 件 自动 运行 ， 并 将 定期 获取 到 的 集群 状态 数据 ， 存 储 在 .marvel-YYYY.MM.DD 索 引 中 ， 以 单 台 Elasticsearch 计 算 ， 该 索引 的 大 小 在 500MB 左 右 。 所 以 ， 如 果 在 小 规模 环境 下 运行 ， 首 先 
请 注意 ， 不 要 让 你 宝贵 的 内 存 都 花 在 marvel 的 数据 索引 上 了 。 


如 果 不 打算 使 用 marvel， 在 各 节点 上 通过 下 行 命令 下 载 : 


# ./bin/plugin -r marvel 


如 果 不 想 让 marve 收 据 索 引 影响 到 生产 环境 Elasticsearch 的 运行 ， 可 以 搭建 单独 的 marve 收 据 集 群 ， 而 生产 数据 集群 上 通过 主动 汇报 的 方式 把 数据 发 送 过 去 。 


在 两 个 集群 都 安装 好 marvel 插 件 后 ， 在 生产 集群 的 elasticsearch.yml 上 添加 如 下 配置 : 


marvel.agent.exporter.es.hosts: [ “marvel-cluster-ip:9200”] 


与 大 多 数 cluster 设 置 一 样 ，marvel 设 置 也 是 可 以 动态 变更 的 : 


# curl -XPUT 127.0.0.1:9200/ cluster/settings -d '{ “transient” : { “marvel.agent.exporter.es.hosts” : [ “192.168.0.2:9200” , ^"192.168.0.3:9200" ] 
i 


T 
数据 接收 端的 marvel 集 群 ( 即 上 一 行 写 的 marvel-cluster-ip 代 表 的 主机 ) 则 添加 如 下 配置 : 


marvel.agent.enabled: false 


即 本 身 不 启用 marvel， 以 免 数据 有 混淆。 


既然 是 Elasticsearch 播 件 ， 访 问 地址 自然 是 插件 式 的 ， 具 体 地 址 为 http:// 


marvel 的 监控 页 面 在 Kibana 3 的 基础 上 稍 有 改造 ， 如 图 13-4 所 示 ， 其 项 部 菜单 栏 设 计 了 一 个 下 拉 选 择 框 ， 可 以 切换 几 个 不 同 纬度 的 仪表 盘 。 


sa Marvel - Overview 
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Marvel 的 信息 展示 能 够 以 Pane| 为 单元 进行 个 性 化 定制 。 每 个 Panel 定 制 的 过 程 比较 类 似 。 这 里 举例 定制 一 个 DOCUMENT COUNT 文 档 数 Panel， 配 置 过 程 如 下 。 


1) 点 击 红 色 椭圆 部 分 ， 添 加 一 个 Panel， 如 图 13-5 所 示 。 


„al Marvel - Overview 


FILTERING « st 


LUSTER SUMMAR Y 


jame: 38 toct. Status: Hodes:? Indices: | Shards; | Data: 30 22 MB CPU: 1% Memory 1 : 1133GB Uptime; 26n Version:! 7 1 
Add 


edi 5 点 击 该 按钮 添加 新 面板 


DOCUMENT COUNT € "^ à $ x SEARCH REQUEST RATE o d] 9 x 


2) 输入 Panel 的 名 字 DOCUMENT COUNT， 如 图 13-6 所 示 。 


Histogram Settings 
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3) 输入 Panel Y 轴 显示 的 值 “Primaries.docx.count” ， 如 图 13-7 所 示 。 
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图 13-7 Y 轴 定义 


4) 选择 展示 风格 ， 如 图 13-8 所 示 。 
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图 13-8 选择 风格 


5) 选择 查看 的 集合 ， 这 里 选择 all， 如 


13-9 所 示 。 
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图 13-9 ”选择 Queries 


6) 一 个 Document Count Panel 就 完成 了 ， 如 


13-10 所 示 。 
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图 13-10 Document Count 面 板 效 果 


之 前 提 到 的 都 是 Elasticsearch 的 sites 类 型 插件 ， 其 实质 是 实时 从 浏览 器 读 取 cluster stats 接 口 


使 


诸如 nagios、zabbix、ganglia、collectd 这 类 监控 系统 。 


本 节 以 Zabbix 为 例 ， 介 绍 如 何 使 用 监控 系统 完成 Elasticsearch 的 监控 报警 。 


数据 并 演 染 页 面 。 这 种 方式 直观 ， 但 不 适合 生产 环境 的 自动 化 监控 和 报警 处 理 。 要 达到 这 个 目标 ， 还 是 需 


Github 上 有 好 几 个 版 本 的 ESZabbix 仓 库 ， 都 源 自 Elastic 公 司 员工 untergeek 最 时 的 贡献 。 但 是 当时 Elasticsearch 还 没有 官方 python 客 户 端 ， 所 以 监控 程序 用 的 都 是 pyes 库 。 对 于 最 新 版 的 
Elasticsearch 来 说 ， 已 经 不 推荐 使 用 了 。 


这 里 推荐 一 个 修改 使 用 了 官方 elasticsearch.py 库 的 衍生 版 。GitHub 地 址 为 : https:// 


TB 


仓库 中 包括 三 个 文件 : 
”ESzabbix.Py 
* ESzabbix.userparm 


* ESzabbix templates.xml 


* /etc/ zabbix/zabbix. externalscripts/ ESzabbix.py 
- /etc/ zabbix/agent, include/ESzabbix.userparm 


然后 在 各 节点 安装 运行 ESzabbix.py 所 需 的 python 库 依赖 : 


# yum install -y python-pbr python-pip python-urllib3 python-unittest2 
# pip install elasticsearch 


安装 成 功 后， 你 可 以 试 运 行 下 面 这 行 命令 ， 看 看 命令 输出 是 否 正 常 : 


# /etc/zabbix/zabbix externalscripts/ESzabbix.py cluster status 


其 中 ， 前 两 个 文件 需要 分 发 到 每 个 Elasticsearch 节 点 上 。 如 果 节 点 上 运行 的 是 yum 安 装 的 zabbix， 二 者 的 默认 位 置 应 该 分 别 是 : 


最 后 一 个 文件 是 zabbix server 上 的 模板 文件 ， 不 过 在 导入 模板 之 前 ， 还 需要 先 创建 一 个 数值 映射 ， 


因 


为 在 模板 中 ， 设 置 了 集群 状态 的 触发 报警 ， 没 有 映射 的 话 ， 报 警 短信 只 有 0、1、2 数 字 不 是 很 易 


创建 数值 映射 ， 在 浏览 器 登录 zabbix-web， 在 菜单 栏 的 Zabbix Administration 中 选择 General 子 菜单 ， 然 后 在 右 侧 下 拉 框 中 点 击 Value Maping。 


选择 create， 新 建 表单 中 填写 : 


name: ES Cluster State 
0 => Green 1 => Yellow 2 => Red 


完成 以 后 ， 即 可 在 Templates 页 中 通过 import 功 能 完成 导入 ESzabbix_ templates.xml, 


在 给 Elasticsearch 各 节点 应 用 新 模板 之 前 ， 需 要 给 每 个 节点 定义 一 个 {$NODENAME} 宏 ， 


13.5.2 ”模板 应 用 


导入 完成 后 ，Zabbix 里 多 出 来 三 个 可 用 模板 。 


体 值 为 该 节点 elasticsearch.yml 中 的 node.name 值 。 从 统一 配 管 的 角度 ， 建 议 大 家 都 设置 为 jp 地 址 。 


1) Elasticsearch Node&Cache 其 中 包括 两 个 Application: ES Cache 和 ES Node。 分 别 有 Node Field Cache Size, Node Filter Cache Size, Node Storage Size 和 Records indexed per 
second 共 计 4 个 item 监 控 项 。 在 完成 上 面 说 的 宏 定义 后 ， 就 可 以 把 这 个 模板 应 用 到 各 节点 ( 即 监控 主机 ) LT. 


2) Elasticsearch Service 只 有 一 个 监控 项 Elasticsearch service status， 做 进程 监控 ， 同 时 也 应 


到 各 节点 上 。 


3) Elasticsearch Cluster 包括 11 个 监控 项 ， 如 下 列 所 示 。 其 中 ，ElasticSearch Cluster Status 这 个 监控 项 连带 有 报警 的 触发 器 ， 并 对 应 之 前 创建 的 那个 Value Map. 


* Cluster-wide records indexed per second 
* Cluster-wide storage size 

* ElasticSearch Cluster Status 

* Number of active primary shards 

* Number of active shards 

* Number of data nodes 

* Number of initializing shards 

* Number of nodes 

: Number of relocating shards 

* Number of unassigned shards 


* Total number of records 


这 个 模板 下 都 是 集群 总 体 情 况 的 监控 项 ， 所 以 ， 运 用 在 一 台 有 Elasticsearch 集 群 读 取 权 限 的 主机 上 即 可 ， 


第 14 章 ”Elasticsearch 在 运 维 监控 领域 的 其 他 应 用 


目前 Elasticsearch 虽 然 以 ELK stack 作 为 主打 产品 ， 但 : 


对 于 Elastic 公 司 来 说 ， 这 些 周边 应 用 ， 也 随时 可 能 成 为 它们 的 后 续 目标 产品 。 就 在 本 书 编写 期 间 ，packetbeat 就 被 Elastic 公 司 收购 了 ， 并 且 可 能 作为 未 来 数据 采集 端的 标准 应 


提前 了 解 其 他 方面 的 多 种 可 能 ， 也 是 非常 有 意义 的 。 本 章 主 要 介绍 以 下 内 容 : 


“Percolator 接 口 ， 这 是 Elasticsearch 中 非常 另类 的 接口 ， 可 以 用 于 实时 过 滤 处 理 。 


优秀 的 分 布 式 设 计 、 灵 活 的 搜索 评分 函数 和 强大 简洁 的 检索 聚合 功能 ， 在 运 维 领域 也 衍生 出 不 少 : 


比如 Zabbix server。 


他 有 趣 的 应 用 方式 。 


- Watchet 报 警 ， 介 绍 Elastic.co 公 司 推 出 的 Watchet 报 警 产品 用 例 及 设计 思路 ， 读 者 可 以 参照 设计 自己 的 Elasticseatch 报 警 产品 。 


packetbeat 抓 包 分 析 ， 通 过 抓 包 解析 方式 分 析 网 络 数据 的 packetbeat 产 品 ， 这 无 疑 是 Elasticseatch 未 来 的 方向 之 一 ， 建 议 读者 关注 。 


“时序 数据 库 ， 探 索 将 Elasticsearch 用 作 时 序数 据 库存 储 方面 的 可 能 性 。 对 比 其 与 Graphite、Zabbix 等 方案 的 优 劣 。 


` Etsy 的 Kale 异 常 检测 ， 该 方案 巧妙 地 利用 了 Elasticsearch 的 相关 性 打分 机 制 ， 可 以 说 是 Elasticsearch 在 监控 领域 一 种 独特 的 运用 。 


14.1 ”Percolator 接 口 


在 运 维 体系 中 ， 监 控 和 报警 总 是 成 双 成 对 地 出 现 。ELK stack 在 时 序 统计 方面 的 便捷 ， 在 很 多 时 候 被 作为 监控 的 一 种 方式 在 使 用 。 那 么 ， 自 然 就 引 上 


对 于 简单 而 且 固 定 需求 的 模式 ， 我 们 可 以 在 Logstash 中 利用 filteVmetric 和 filter/ruby 等 插件 做 预 处 理 ， 直 接 output/nagios 或 output/nagios 来 报警 ; 但 是 对 了 


就 无 能 为 力 了 。 


目前 比较 通行 的 办 法 有 以 下 两 种 : 


1) 对 于 匹配 报警 ， 采 用 Elasticsearch 的 Percolator 接 口 做 响应 报警 。 


2) 对 于 时 序 统计 ， 采 用 定时 任务 方式 ， 发 送 Elasticsearch aggs 请 求 ， 分 析 响 应 体 报警 。 


Percolator 接 口 和 我 们 习惯 的 搜索 接口 正好 相反 ， 它 要 求 预先 定义 好 query， 然 


比如 我 们 通过 syslog 来 发 现 硬件 报错 的 时 候 ， 可 以 预先 定义 query: 


# curl -XPUT http://127.0.0.1:9200/syslog/.percolator/memory -d '( 


后 通过 接口 


提交 文档 看 能 


。 所 以 ，ELK stack? 


出 一 个 问题 : ELK stack 如 何 做 报警 ? 


匹配 上 哪个 query。 也 就 是 说 ， 这 是 一 个 实时 的 模式 过 滤 接 


户 


针对 全 局 的 、 更 复杂 的 情况 ，Logstash 


"wen id 
query string  : ( 
"default field" "message" , 
"default operator" "OR, 
"query" "mem DMA segfault page allocation AND severity:»2 AND program:kernel" 
} 
} 
' 
# curl -XPUT http://127.0.0.1:9200/syslog/.percolator/disk -d '( 
"Weny i00, 
query string  : ( 
"default field" 
"default operator" " 
"query" “scsi sata hdd sda AND severity:»2 AND program:kernel" 


"message" , 


} 
p 


然后 ， 将 标准 的 数据 写 入 请 求 稍微 做 一 点 改动 : 


# curl -XPOST http://127.0.0.1:9200/syslog/msg/ percolate -d '( "doc" : ( "timestamp" 
H 
} 


' 


"Jul 17 03:57:23" , "host" 


"localhost' , "program" 


"kernel' , "facility" 


: 0, 


得 到 如 下 结果 : 


: 1, "matches" : [ 


“syslog” , " id" "memory" 


从 结果 可 以 看 出 来 ， 这 条 syslog 日 志 匹 配 上 了 memory 异 常 。 接 下 来 就 可 以 发 送 给 报警 系统 了 。 


如 果 是 syslog 索 引 中 已 经 有 的 数据 ， 也 可 以 重新 过 一 遍 Percolator 接 口 : 


# curl -XPOST http://127.0.0.1:9200/syslog/msg/existsid/ percoloate 


14.2 ”Watcher 报 警 


利用 更 复杂 的 query DSL 做 Percolator 请 求 的 示例 ， 推 荐 阅读 官网 这 篇 geo 定 位 的 文章 : https://www.elastic.co/blog/using-percolator-geo-tagging。 


针对 报警 的 需求 ，Elasticsearch 官 方 也 在 最 近 开 发 了 Watcher 商 业 产 品 ， 与 Shield 一 样 以 Elasticsearch 插 件 形式 存在 。 所 以 Watcher 和 Shield、Marvel 一 样 插件 式 安装 即 可 :: 


# bin/plugin -i elasticsearch/license/latest 
# bin/plugin -i elasticsearch/watcher/latest 


在 使 用 Watcher 时 ，Elasticsearch 也 提供 了 标准 的 RESTful 接 口 ， 示 例如 下 : 


# curl -XPUT http://127.0.0.1:9200/ watcher/watch/error status -d' 
{ 
“trigger” : { 


"schedule" : { “interval” : “Sm” } 
), 
“input” : { 
“search” : { 
“request” : { 
“indices” : [ "«logstash-(now/d]»" , “<logstash-{now/d-1d}>” ], 
“body” : { 
"query" i 
filtered : 
“query” : : { “status” “error” }}, 
"filter" : ( “etimestamp” : ( "from" "now-5m" }}} 
} 
j 
i 
i 
“condition” : ( 
"compare" : { "ctx.payload.hits.total" : ( “gt” : 0 }} 
), 
"transform : ( 
“search” : ( 
"request" : { 
"indices" [ *«logstash-(now/d)»" , *«logstash-(now/d-ld)»" ], 
body" 
"query" cd 
filtered sf 
“query” : { “match” : { “status” “error” }}, 
“filter” : { “range” : ( “@timestamp” : { "from "now-5m" }}} 
} 
h 
aggs" :( 
"topn" : { 
"terms" : 
"field" "userid" 
H 
} 
} 
} 
} 
} 
1 
"actions" : ( 
"email admin" : { 
"throttle period" "15m" , 
"email' : 
^to" : “adminedomain”， 
"subject" "Found ((ctx.payload.hits.total)) Error Events" , 
"priority" "high' , 
"body" “Top10 users: Wn((4ctx.payload.aggregations.topn.buckets])Nt( (key) 


((doc count) JAn( (/ctx.payload.aggregations.topn.buckets]]" 


1) 每 5 分 钟 ， 向 最 近 两 天 的 logstash-yyyy.MM.dd 索 引发 起 一 次 条 件 为 最 近 五 分 钟 ，status 字 段 内 容 为 error 的 查询 请 求 。 

2) 对 查询 结果 做 hits 总 数 大 于 0 的 判断 。 

3) 如 果 为 真 ， 再 请 求 一 次 上 述 条 件 下 ，userid 字 段 的 Top 10 数 据 集 作 为 后 续 处 理 的 来 源 。 

4) 如 果 最 近 15 分 钟 内 未 发 送 过 报警 ， 则 向 admin@ domain 邮 箱 发 送 一 个 标题 为 “Found N erroneous events”， 内 容 为 “Top10 users” 列 表 的 报警 邮件 。 


整个 请 求 体 顺 序 执 行 。 目 前 trigger 只 支持 scheduler 方 式 ，input 支 持 search 和 http 方 式 ，actions 支 持 email、logging 和 webhook 方 式 ，transform 是 可 选项 ， 而 且 可 以 设置 在 actions 里 ， 不 同 
actions 做 不 同 的 payload 转 换 。 


在 condition、transform 和 actions 中 ， 默 认 使 用 Watcher 增 强 版 的 xmustache 模 板 语言 ， 也 可 以 使 用 固化 的 脚本 文件 ， 例 如 ， 如 果 有 threshold_hits.groovy， 则 可 执行 : 


“condition” : ( 
"script" : ( 
"file" : “threshold hits" , 
“params” : ( 
“threshold” : 0 
l 
} 
} 


完整 的 Watcher 揪 件 内 部 执行 流程 如 图 14-1 所 示 。 相 信 有 编程 能 力 的 读者 都 可 以 用 crontab/at 配 合 curl、email 工 具 仿 造 出 来 类 似 功 能 的 shell 脚 本 。 


[v 


for each action for each action 


transtorm 
payload 


exec action 


done 


图 14-1 Watcher 流 程 图 


如 果 需 要 一 款 开 源 的 类 似 实现 ， 可 以 尝试 Yelp 开 源 的 ElastAlert 系 统 。 官 方 文档 地 址 为 : http://elastalert.readthedocs.org/, 


在 search 中 ， 对 indices 内 容 可 以 写 完整 的 索引 名 比如 syslog， 也 可 以 写 通配符 比如 logstash-*， 还 可 以 写 时 序 索 引 动态 定义 方式 如 <logstash-{now/d}j>。 而 这 个 动态 定义 ，Watcher 是 支持 根据 时 区 来 


确定 的 ， 这 个 需要 在 elasticsearch.yml 里 配置 一 行 : 


watcher.input.search.dynamic indices.time zone: '+08:00' 


1433 packetbeat 抓 包 分 析 


之 前 已 经 提 到 过 ，packetbeat 已 经 被 Elastic 公 司 收 归 旗下 ， 未 来 就 会 替代 logstash-forwarder 成 为 ELK stack 套 件 | 


forwarder 呢 ? 


的 一 部 分 。 那 么 ， 为 什么 Elastic 公 司 如 此 看 好 packetbeat 项 目 ， 不 惜 废 掉 logstash- 


packetbeat 和 logstash-forwarder 一 样 ， 也 是 一 个 golang 写 的 开源 项 目 。 其 特色 在 于 ，logstash-forwarder 的 数据 来 源 是 文件 或 者 标准 输入 ， 都 是 文本 流 。 而 packetbeat 采 用 libpcap 库 ， 抓 取 网 络 流 


量 ， 识 别 其 中 的 特定 网 络 协议 ， 自 动 按照 协议 规范 ， 将 网 络 流量 包 划 分 成 事件 字段 ， 写 入 到 Elasticsearch 中 。 


目前 packetbeat 支 持 的 网 络 协议 有 : HTTP、MySQL、PostgreSQL、Redis 和 Thrift。 


对 于 很 多 ELK stack 新 手 来 说 ， 面 对 的 很 可 能 就 是 几 种 常用 数 所 
帮助 。 


居 流 ， 而 书写 Logstash 正 则 是 一 个 耗 时 耗 力 的 重复 劳动 ， 文 件 落 地 本 身 又 是 多 余 操 作 ，packetbeat 的 运行 方式 ， 无 疑 是 对 新 手 入 门 极 大 的 


目前 packetbeat 项 目地 址 为 : https://github.com/elastic/packetbeat, 


143.1 安装 部 署 


packetbeat 同 样 有 已 经 编译 完成 的 软件 包 可 以 直接 安装 使 用 。 需 要 注意 的 是 ，packetbeat 支 持 不 同 的 抓 包 方式 ， 也 就 有 不 同 的 依赖 。 比 如 最 通用 的 pcap， 就 要 求 安装 libpcap 包 ，pf_ring 就 要 求 安装 


pfring&, 


# yum install libpcap 


4 rpm -ivh http://www.nmon.net/packages/rpm6/x86 64/PF RING/pfring-6.1.1-83.x86 64.rpm 
4 rpm -ivh https://download.elasticsearch.org/beats/packetbeat/packetbeat- 


1.0.0-Betal-x86 64.rpm 


packetbeat 还 附带 了 一 个 定制 的 Elasticsearch 模 板 ， 要 在 正式 使 用 前 导入 Elasticsearch 中 。 


# curl -XPUT 'http://localhost:9200/ template/packetbeat' -d8/etc/packetbeat/ 


packetbeat.template.json 


14.3.2 ”配置 示例 


通过 RPM 安装 的 packetbeat 配 置 文件 位 于 /etc/packetbeat/packetbeat.yml。 其 基础 示例 如 下 : 


/etc/packetbeat/packetbeat.ymlLl。 其 基础 示例 如 下 : 


shipper: 
tags: [ “web” ] 
interfaces: 
device: any 
type: af packet 
buffer size mb: 100 


protocols: 
http: 
ports: [80, 8080] 
send headers: [ “User-Agent” ] 
real ip header: "X-Forwarded-For" 
mysql: 
ports: [3306] 
output: 
elasticsearch: 


enabled: true 
host: ^"192.168.0.2" 


shipper 默 认 会 以 本 机 IP 地 址 作为 name，interfaces 支 持 pcap，af_packet 和 pf _ring 三 种 模式 。output 除 了 直接 给 Elasticsearch， 以 外 ， 还 可 以 给 Redis， 再 


Elasticsearch。 


output: 

elasticsearch: 
enabled: false 

redis: 
enabled: true 
host: ^"192.168.0.3" 
port: 6379 
save topology: true 


logstash-input-redis 接 收 数据 写 


然后 Logstash 配 置 如 下 ， 注 意 因 为 packetbeat 自 带 的 template 是 匹配 packetbeat-* 索 引 的 : 


input ( 

redis { 
codec => “json” 
host => “192.168.0.3” 
port => 6379 
data type => “list” 
key => “packetbeat” 

} 


} 
output { 
elasticsearch { 

protocol => “http” 
host => “127.0.0.1” 
sniffing => true 
manage template => false 
index => "packetbeat-$ (4YYYY.MM.dd)" 


14.3.3 dashboard 效果 


针对 packetbeat 自 动 识 别 的 不 同 协议 ，packetbeat 还 自 带 了 几 个 预定 义 好 的 Kibana dashboard 方 便 使 用 和 查看 。 包 括 : 


* Packetbeat Statistics: 针对 HTTP 和 标准 流量 事件 的 性 能 统计 仪表 盘 。 
“ Packetbeat Search: 用 来 搜索 关键 字 的 仪表 盘 。 

* MySQL Performance: MySQL 性 能 分 析 仪 表盘 。 

* PgSQL Performance: PgSQL 性 能 分 析 仪 表盘 。 


预定 义 仪表 盘 的 导入 方式 如 下 : 


# git clone https://github.com/elastic/packetbeat-dashboards 
# cd packetbeat-dashboards 
# ./load.sh http://192.168.0.2:9200 


MySQL Performance 效 果 如 图 14-2 所 示 。 
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图 14-2 MySQL Performance zi Æ 


Packetbeat Statistics 效 果 如 图 14-3 所 示 。 
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图 14-3  Packetbeatzk X 


14.34 Kibana 3 拓扑 图 


其 实在 Kibana 4 推出 之 前 ，packetbeat 曾 经 自己 fork 了 一 个 Kibana 3 的 分 支 ， 并 在 此 基础 上 二 次 开发 了 一 个 专门 用 来 展示 网 络 拓扑 结构 的 面板 ， 叫 作 force panel。 该 特性 至 今 依 然 只 能 运行 在 Kibana 
3 上 。 所 以 ， 需 要 网 络 拓扑 展现 的 用 户 ， 还 得 继续 使 用 Kibana 3。 部 署 方式 如 下 : 


# curl -L -O https://github.com/packetbeat/kibana/releases/download/v3.1.2-pb/ 
kibana-3.1.2-packetbeat.tar.gz 

# tar xzvf kibana-3.1.2-packetbeat.tar.gz 

# curl -L -0 https://download.elasticsearch.org/beats/packetbeat/packetbeat- 
dashboards-k3-1.0.0-Betal.tar.gz 

# tar xzvf packetbeat-dashboards-k3-1.0.0-Betal.tar.gz 

# cd packetbeat-dashboards-k3-1.0.0-Betal/ 

# ./load.sh 192.169.0.2 


force panel 示 例如 图 14-4 所 示 。 注 意 ，force panel 用 到 的 数据 ， 其 实质 是 对 各 来 源 IP 分 别 请 求 目 的 I!P， 对 Elasticsearch 的 计算 量 要 求 较 大 ， 并 不 适合 在 高 流量 、 高 负载 的 条 件 下 使 用 。 
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Qbana 


pfring 抓 包 模 式 的 原 厂 (ntop 公 司 ) 也 有 类 似 packetbeat 的 计划 。ntopng/nProbe 除 了 储存 到 SQLite 以 外 ， 也 开始 支持 存储 到 Elasticsearch 中 。 不 过 它们 推荐 采用 的 是 dashboard， 它 是 Kibana 3 的 


另 一 个 fork 分 支 ， 叫 作 Qbana， 效 果 见 图 14-5。 


有 兴趣 的 读者 可 以 参考 ntop 官 方 文档 : http://www.ntop.org/ntopng/exploring-your-traffic-using-ntopng-with-elasticsearchkibana/。 


144 时序 数据 库 


之 前 已 经 介绍 过 ，Elasticsearch 默 认 存 储 数据 时 ， 是 有 索引 数据 、_all 全 文 索引 数据 、_source JSON 字 符 串 三 份 的 。 其 中 ， 索 引 数 据 由 于 倒 排 索 引 的 结构 ， 压 缩 比 非常 高 。 
求 下 ， 可 以 只 保留 索引 数据 ， 以 极 小 的 容量 代价 ， 换 取 Elasticsearch 灵 活 的 数据 结构 和 聚合 统计 功能 。 


在 监控 系统 中 ， 对 监控 项 和 监控 数据 的 设计 一 般 是 这 样 : 
- metric. path value timestamp (Graphite 设 计 ) 


* ("host": "Host name 1", "key": "item key", "value": "33", "clock": 1381482894} (Zabbix 设 计 ) 


此 ， 在 某 些 特定 环境 和 需 
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图 14-5  Qbanazt $ 


这 些 设计 有 个 共同 点 ， 数 据 是 二 维 平面 的 。 以 最 简单 的 访问 请 求 状态 监控 为 例 ， 一 次 请 求 ， 可 能 转换 出 来 的 metric_path 或 者 说 key 就 有 : (city, isp, host, upstream]. 


{urlpathhttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/15426/OEBPS/Text/...}.{status, rt, ut, size，speed} 这 么 多 种 。 


个 ， 就 是 20000 个 组 合 。 意 味 着 需要 发 送 20000 条 数据 ， 做 20000 次 存储 。 


而 在 Elasticsearch 里 ， 这 就 是 实 实在 在 1000 条 日 志 。 而 且 在 多 条 日 志 的 时 候 ， 因 为 词 元 的 相对 固定 ， 压 缩 比 还 会 更 高 。 所 以 ， 使 用 Elasticsearch 来 做 时 序 监控 数据 的 存储 和 查询 ， 


对 时 序数 据 ， 关 键 就 是 定义 缩减 数据 重复 。template 示 例如 下 : 


假设 urlpath 有 1000 


是 完全 可 行 的 办 法 。 


{ “order” : 2, “template” :  "logstash-monit-*" , "settings" 
), "mappings  : ( ' default " : ( " source" : ( "enabled" : false 
), “all” : ( “enabled” : false 
j 
) » 
), “aliases Se 


} 


如 果 有 些 字段 ， 是 完全 不 用 Query， 只 参加 Aggregation 的 ， 还 可 以 设置 : 


"properties" : ( "sid" : ( “index” : “no” , "doc values” : true, "type" : "string" 


] 


关于 Elasticsearch 用 作 rrd 用 途 ， 与 MongoDB 等 其 他 工具 的 性 能 测试 与 对 比 ， 可 以 阅读 腾讯 工程 师 写 的 系列 文章 : http://segmentfault.com/a/1190000002690600。 


14.5 ”Etsy 的 Kale 异 常 检测 


Kale 系 统 是 Etsy 公 司 开源 的 一 个 监控 分 析 系 统 。Kale 分 为 两 个 部 分 : skyline 和 oculus。skyline 负 责 对 时 序数 据 进 行 概 率 分 布 校 验 ， 对 校 验 失败 率 超过 阔 值 的 时 序数 据 发 报警 ，oculus 负 责 给 被 报警 的 时 


序 ， 找 出 趋势 相似 的 其 他 时 序 作为 关联 性 参考 。 官 方 博客 地 址 为 : http://codeascraft.com/2013/06/11/introducing-kale/。 


看 到 “相似 ”两 个 字 ， 你 一 定 想到 了 。 没 错 ，oculus 组 件 就 是 利用 了 Elasticsearch 的 相似 度 打分 。 


在 oculus 中 ， 为 Elasticsearch 的 org.elasticsearch.script.ExecutableScript 扩 展 了 DTW 和 Euclidian 两 种 NativeScript。 可 以 在 界面 上 选择 用 其 中 某 一 种 算法 来 做 相似 度 打 分 ， 如 


图 14-6 所 示 。 
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然后 相似 度 最 高 的 几 个 时 序 图 就 依次 排列 出 来 了 。 


Euclidian 即 欧 几 里 得 距离 ， 是 时 序 相似 度 计 算 里 最 基础 的 方式 。 


DTW 即 动态 时 间 规整 (Dynamic Time Warping) ， 也 是 时 序 相似 度 计算 的 常用 方式 ， 它 和 欧 几 里 得 距离 的 差别 在 于 ， 欧 几 里 得 距离 要 求 比 对 的 时 序数 
据 并 不 要 求 长 度 相等 。 在 运 维 监控 来 说， 也 就 是 延 后 一 定时 间 发 生 的 相近 趋势 也 可 以 以 很 高 的 打分 项 排名 靠 前 。 


09:40 


居 是 一 一 对 应 的 ， 而 动态 时 间 规 整 计算 的 时 序数 


不 过 ，oculus 插 件 仅 更 新 到 支持 Elasticsearch-0.90.3 版 本 为 止 。Etsy 性 能 优化 团队 在 OReilly 2015 大 会 上 透露 ， 他 们 内 部 已 经 根据 Kale 的 经 验 教训 ， 重 新 开发 了 Kale 2.0 版 。 预 计 会 在 2015 年 秋季 开 


源 。 大 家 一 起 期 待 吧 ! 


第 三 部 分 Kibana 


- 第 15 章 ”Kibana 的 产品 对 比 
"第 16 章 Kibana3 
- 第 17 章 ”Kibana 3 源码 解析 
“第 18 章 Kibana4 


- 第 19 章 ”Kibana 4 源码 解析 


Logstash 早 期 曾经 自 带 了 一 个 特别 简单 的 logstash-web 用 来 查看 Elasticseatch 中 的 数据 。 其 功能 太 过 简单 ， 于 是 Rashid Khan 用 PHP 写 了 一 个 更 好 用 的 Web， 取 名 叫 Kibana。 这 个 PHP 版 本 的 Kibana 发 布 时 间 是 
2011 年 12 月 11 日 。 


Kibana 迅 速 流行 起 来 ， 不 久 的 2012 年 8 月 19 日 ，Rashid Khan 用 Ruby 重 写 了 Kibana， 也 被 叫做 Kibana 2。 因 为 Logstash 也 是 用 Ruby 写 的 ， 这 样 Kibana 就 可 以 替代 原先 那个 简陋 的 logstash-web 页 面 了 。 


目前 我 们 看 到 的 Angularjs 版 本 Kibana 其 实 原名 叫 elasticsearch-dashboard， 但 跟 Kibana 2 作者 是 同一 个 人 ， 换 和 句 话说 ，Kibana 比 Logstash 还 早 就 进 了 Elasticsearch 名 下 。 这 个 项 目 改 名 Kibana 是 在 2014 年 2 月 ， 也 被 
叫做 Kibana 3。 全 新 的 设计 一 下 子 风靡 DevOps 界 。 随 后 其 他 社区 纷纷 借鉴 ，Graphite 目 前 最 流行 的 Grafana 界 面 就 是 由 此 而 来 ， 至 今 代码 中 还 留存 有 十 余 处 kbn 字 样 。 


2014 年 4 月 ，Kibana 3 (K3) 停止 开发 ，Elasticsearch 公 司 集中 人 力 开始 Kibana4 (K4) 的 重 构 ， 在 2015 年 初 发 布 了 使 用 JRuby 做 后 端的 beta 版 后 ， 于 3 月 正式 推出 使 用 node.js 做 后 端的 正式 版 。 由 于 设计 思路 
上 的 差别 ， 一 些 K3 适 宜 的 场景 并 不 在 K4 考 虑 范围 内 ， 所 以 ， 至 今 K3 和 K4 并 存 使 用 。 本 书 也 会 分 别 讲解 两 者 。 


第 15 章 ”Kibana 的 产品 对 比 


Kibana 4 正式 版 于 2015 年 初 发 布 ， 至 今 已 近 半年 。 但 是 本 书 依然 将 Kibana 3 和 4 两 个 版 本 分 别 阐述 ， 并 推荐 大 家 同时 了 解 两 个 系统 。 因 为 二 者 分 别 基于 不 同 接口 ， 不 同 目的 ， 采 取 了 不 同 的 页 面 设计 和 
逻辑 ， 所 以 在 不 同 场景 下 各 有 优势 。 本 章 会 从 设计 原理 层面 稍 作 和 解释 ， 免 受 凑 字 骗 钱 之 训 。 主 要 内 容 包 括 Kibana 3 的 设计 思路 和 功能 、Kibana 4 的 设计 思路 和 功能 、 与 Hadoop 体 系 的 区 别 、Splunk 场 景 参 
考 。 


15.1 Kibana 3 的 设计 思路 和 功能 


本 书 一 开始 就 提 到 ，Kibana 3 在 设计 之 初 ， 有 另 一 个 名 字 ， 叫 elasticsearch dashboard。 事 实 上 ， 整 个 Kibana 3 就 是 一 个 围绕 着 dashboard 构 建 的 单 页 应 用 。 所 以 ， 在 页 面 逻 辑 上 ，Kibana 3 异常 简 
洁 。 大 量 的 代码 和 逻辑 ， 都 下 放 到 panel 层 次 上 。 每 个 panel 要 独立 完成 自己 的 可 视 化 设计 、 数 据 请 求 、 数 据 处 理 、 数 据 泻 染 。panel 和 panel 之 间 ， 则 几乎 毫 无 关联 。 简 单一 点 看 ， 整 个 页 面 就 像 是 一 堆 


iframe 一 样 。 


而 panel 的 设计 ， 则 是 以 使 用 者 角度 来 考虑 的 。Kibana 3 尽量 提供 能 让 运 维 人 员 一步 到 位 的 使 用 策略 。 即 使 用 者 只 需要 了 解 panel 的 配置 页 面 能 填 什 么 参数 ， 得 到 什么 可 视 化 结果 。 


最 明显 的 例子 就 是 trend panel, trend panel 背 后 其 实 是 针对 今天 和 上 昨天， 分别 发 起 两 次 请 求 ， 然 后 再 拿 两 次 请 求 的 结果 ， 做 一 次 除法 ， 计 算 涨 跌幅 。 这 个 除法 计算 ， 是 在 浏览 器 端 完成 的 。 


类 似 在 浏览 器 端 完成 的 还 有 histogram panel 的 hits、second 等 的 计算 。 


此 外 ，Kibana 3 还 有 一 个 非常 有 用 的 功能 ，setting 中 的 index pattern， 是 可 以 输入 多 个 模式 ， 比 如 accesslog-[YYYY.MM.DD]，syslog-[YYYY.MM.DD]， 这 样 就 可 以 在 同一 个 面板 上 ， 看 到 来 自 不 同 
索引 的 数据 的 情况 。 


152 Kibana 4 的 设计 思路 和 功能 


从 新 特性 来 说 ，Kibana 4 全 面 支持 Aggregation 接 口 ， 还 有 更 多 的 可 视 化 选择 ， 可 以 任意 拖 动 自动 对 齐 的 挂件 框架 ， 保 存在 URL 可 以 跨 页 面 保持 的 检索 条 件 ， 以 及 对 页 面 请 求 的 内 部 排队 机 制 。 


给 页 中 ， 用 d3:js 实 现 的 可 视 化 构建 器 ， 与 请 求 Elasticsearch 数 据 的 聚合 选择 器 ， 又 是 各 自 独立 的 插件 。 


也 就 是 说 ，Kibana 4 在 使 用 Aggregation 接 口 提供 更 复杂 功能 和 更 高 性 能 的 同时 ， 彻 底 改 变 了 用 户 的 使 用 形式 。 
想 清楚 可 视 化 的 展现 形式 ， 充 分 理解 数据 字段 的 作用 。 然 后 才能 实现 想 要 的 结果 。 毫 无 疑问 ， 这 是 有 学 习 成 本 的 。 


户 必须 明确 了 解 Elasticsearch 各 个 aggs 接 口 的 意义 、 请 求 和 响应 体 的 数据 情况 ; 还 要 


至 于 像 Kibana 3 那 种 在 浏览 器 端 计算 的 功能 ，Kibana 4 中 则 完全 没有 。Elasticsearch 2.0 将 会 提供 一 种 pipeline aggregation 特 性 ， 目 前 猜测 或 许 Kibana 4 会 在 这 个 Elasticsearch 新 特性 的 基础 上 来 实 
现 类 似 功能 。 


在 界面 美观 方面 。Kibana 4 至 今 未 提供 类 似 Kibana 3 中 的 Query 设 置 功能 ， 包 括 Query 别 名 和 颜色 选择 器 这 两 个 常用 功能 都 没有 。 直 接 导 致 目前 Kibana 4 的 图 例 几乎 毫 无 作用 。 


在 filter 方 面 ，Kibana 4 用 filter agg 蔡 代 了 Kibana 3 使 用 的 facet filter。 页 面 表现 形式 上 ，Kibana 3 是 在 页 面 顶部 添加 Query 输 入 框 ， 全 局 生效 ; Kibana 4 是 在 Visualize 页 添加 aggs， 单 个 面板 生效 。 
依然 需要 多 查询 条 件 对 比 的 用 户 ， 需 要 一 个 个 面板 创建 ， 非 常 麻烦 。 


15.3 ”与 Hadoop 体 系 的 区 别 


Kibana 因 其 丰富 的 图 表 类 型 和 漂亮 的 前 端 界 面 ， 被 很 多 人 理解 成 一 个 统计 工具 。 而 我 个 人 认为 ，ELK 这 一 套 体系 ， 不 应 该 和 Hadoop 体 系 同 质 化 。 定 期 的 离线 报表 ， 不 是 Elasticsearch 专 长 所 在 (多 花 
费 分 词 、 打 分 这 些 步 骤 在 高 负载 压力 环境 上 太 奢 侈 了 ) ， 也 不 应 该 由 Kibana 来 完成 (每 次 刷新 都 是 重新 计算 ) 。Kibana 的 使 用 场景 应 该 集中 在 两 方面 : 


“ 实时 监控 。 通 过 histogram 面 板 ， 配 合 不 同 条 件 的 多 个 queties 可 以 对 一 个 事件 走 很 多 个 维度 组 合 出 不 同 的 时 间 序 列 走势 。 时 间 序 列 数据 是 最 常见 的 监控 报警 了 。 


- 问题 分 析 。 通 过 Kibana 的 交互 式 界 面 可 以 很 快 地 将 异常 时 间或 者 事件 范围 缩小 到 秒 级 别 或 者 个 位 数 。 期 望 一 个 完美 的 系统 可 以 给 你 自动 找到 问题 原因 并 且 解 决 是 不 现实 的 ， 能 够 让 你 三 两 下 就 从 TB 级 
的 数据 里 看 到 关键 数据 以 便 做 出 判断 就 很 棒 了 。 这 时 候 ， 一 些 非 histogram 的 其 他 面板 还 可 能 会 体现 出 你 意 到 的 价值 。 全 局 状态 下 看 似 很 普通 的 结果 ， 可 能 在 你 锁定 某 个 范围 的 时 候 发 生 剧烈 的 反方 向 的 
变化 ， 这 时 候 你 就 能 从 这 个 维度 去 重点 排查 。 而 表格 面板 则 最 直观 的 显示 出 你 最 关心 的 字段 ， 加 上 排序 等 功能 。 入 库 前 字段 切 分 好 ， 对 于 排 错 分 析 真 的 至 关 重 要 。 


154 _ Splunk 场景 参 


关于 ELK 的 用 途 ， 我 想 还 可 以 参照 其 对 应 的 商业 产品 Splunk 的 场景 ， 因 为 ELK stack 被 称 为 穷人 版 的 Splunk。 自 然 ， 我 们 可 以 从 splunk 的 场景 说 明 中 ， 学 习 到 如 何 更 好 地 使 用 ELK stack, 


使 用 Splunk 的 意义 在 于 使 信息 收集 和 处 理智 能 化 。 而 其 操作 智能 化 表现 在 [1]: 


1) 搜索 ， 通 过 下 钻 数据 排查 问题 ， 通 过 分 析 根本 原因 来 解决 问题 ; 


2) 实时 可 见 性 ， 可 以 将 对 系统 的 检测 和 警报 结合 在 一 起 ， 便 > 于 跟踪 SLA 和 性 能 问题 ; 


3) 历史 分 析 ， 可 以 从 中 找 出 趋势 和 历史 模式 ， 行 为 基线 和 阔 值 ， 生 成 一 致 性 报告 。 


可 以 看 出 ， 基 于 灵活 的 搜索 和 实时 可 视 化 这 两 项 能 力 ， 做 无 确定 因素 的 故障 和 性 能 问题 定位 ， 是 Splunk (ELK) 与 传统 大 数据 工具 在 用 法 上 最 大 的 区 别 。 而 场景 方面 ，Splunk 司 则 把 自己 的 产品 解决 
方案 划分 成 以 下 几 个 方面 : 


“ 应 用 程序 管理 。 尤 其 是 在 “微服 务 ” 概 念 盛行 的 现在 ， 业 务 调 用 的 复杂 度 越 来 越 高 。 前 不 久 携程 网 发 生 的 那 起 故障 ， 业 务 恢复 耗费 数 小 时 ， 主 要 就 因为 要 逐一 确认 名 模块 本 身 的 状态 。 这 种 情况 下 ， 
不 同业 务 单 元 之 间 想 通过 统一 框架 埋 点 的 方式 来 实现 诊断 分 析 ， 难 度 实在 太 大 。 采 用 日 志 数 据 配合 APM 工 具 ， 将 会 逐渐 成 为 主流 。 


“ IT 运 维 管理 。 记 录 系 统 和 程序 层面 的 变更 状态 ， 通 过 对 变更 的 时 间 轴 审核 验证 和 报表 ， 在 意外 故障 中 ， 快 递 定位 变更 造成 的 影响 。 新 浪 网 故障 管理 组 的 数据 ，60% 以 上 的 故障 ， 是 因为 变更 引起 的 。 
快速 定位 具体 变更 ， 快 速 回 滚 ， 降 低 MTTR， 也 是 运 维 工作 的 重要 一 环 。 


安全 审计 。 通 过 对 网 络 设备 ，HTTP 访 问 等 数据 的 模式 分 析 ， 发 现 和 过 滤 安 全 问题 。 这 部 分 也 是 目前 日 志 分 析 领 域 最 有 “ 钱 ” 景 的 地 方 。 国 内 最 几 年 在 日 志方 面 的 创业 公司 ， 大 多 集中 在 安全 审计 方 


: 业务 分 析 。 在 搜索 能 力 和 主动 监控 的 基础 上 ， 由 动态 的 可 视 化 提供 更 深刻 的 业务 洞察 分 析 (Insight) 。 在 Splunk 的 案例 中 ， 有 机 场 航班 、 人 口 统计 的 示例 。 在 Elasticsearch 的 案例 中 ， 有 美国 大 选 和 LBS 
的 示例 。 不 过 ， 目 前 来 说 ， 业 务 分 析 这 部 分 ， 只 占 Splunk 收 入 的 不 到 五 分 之 一 。 可 以 说 并 不 是 主要 场景 。 


可 以 看 出 来 ， 这 些 场景 同样 是 基于 搜索 和 可 视 化 衍生 得 出 的 。 


[1] 参见 《Splunk 大 数据 分 析 》 (Peter Zadrozng 著 ) ， 机 械 工业 出 版 社 引进 出 版 。 


第 16 章 Kibana 3 


Kibana 3 是 一 个 使 用 Apache 开 源 协议 ， 基 于 浏览 器 的 Elasticsearch 分 析 和 搜索 仪表 盘 。Kibana 3 非常 容易 安装 和 使 用 。 整 个 项 目 都 是 用 HTML 和 JavaScript 写 的 ， 所 以 Kibana 3 不 需要 任何 服务 器 端 组 
件 , 一 个 纯 文本 发 布 服务 器 就 够 了 。 本 章 会 介绍 以 下 内 容 : 


“Kibana 3 入 门 。 以 一 个 实际 的 数据 集 查 询 案 例 ， 带 读者 浏览 一 遍 Kibana 3 的 界面 用 法 ， 作 为 入 门 课程 。 

: configjs 配 置 。 介 绍 Kibana 3 中， 唯一 需要 提前 预定 义 的 配置 文件 ，configjs。 

“ 页 面 布局 。 更 详细 地 介绍 Kibana 3 的 页 面 设计 ， 以 及 相关 组 件 具体 的 操作 方式 。 

“ 各 panel 功 能 。 这 是 本 章 重点 内 容 ， 会 详细 解释 Kibana 3 中 每 个 panel 的 具体 配置 用 法 和 相应 的 可 视 化 效果 。 

“ dashboard 的 保存 和 载 入 。 介 绍 最 终 定制 完成 的 仪表 盘 的 保存 ,分享 和 加 载 办 法 。 

“ 自 定义 dashboard 功 能 。 介 绍 仪表 盘 定 制 的 两 种 高 级 方案 。 适 合资 深 用 户 ， 通 过 代码 编辑 手段 ， 直 接生 成 动态 仪表 盘 效 果 。 


“ 认证 授权 。 从 简 入 繁 地 依次 介绍 三 种 Kibana 3 的 权限 控制 方案 ， 供 读者 根据 自己 的 环境 选择 使 用 。 


16.1 Kibana 3 入 门 


Kibana 对 实时 数据 分 析 来 说 是 特别 适合 的 工具 。 本 节 首 先 让 你 快速 入 门 ， 了 解 Kibana 所 能 做 的 大 部 分 事情 。 


16.1.1 ”准备 工作 


在 正式 开始 Kibana 3 的 讲解 之 前 ， 需 要 预先 准备 一 些 条 件 ， 包 括 部 署 环境 和 导入 演示 的 数据 集 。 本 节目 的 是 实地 展示 一 下 Kibana 3 最 主要 的 功能 概 狐 ， 所 以 将 采用 官方 提供 的 一 个 现成 的 数据 集 CPI 
比 亚 全集 ， 相 当 高 大 上 的 示例 ) ， 保 证 大 家 都 能 下 载 到 源 数据 。 


首先 需要 准备 Elasticsearch 环 境 ， 这 一 步 在 之 前 章节 已 经 介绍 过 。 


然后 部 署 单机 的 Kibana 3 环境 。 这 里 有 几 种 选择 : 


“下载 官方 编译 过 的 Kibana 3 包 : 


# wget https://download.elastic.co/kibana/kibana/kibana-3.1.2.tar.gz 


“ 使 用 我 增强 改进 过 的 Kibana 3 源码 库 : 


4 git clone https://github.com/chenryn/kibana.git 


考虑 后 续 介绍 章节 会 有 一 些 基于 我 个 人 版 本 的 内 容 ， 推 荐 大 家 采用 后 一 种 选择 。 


Kibana 3 是 纯 静态 文件 ， 所 以 直接 发 布 即 可 ， 作 为 入 门 章节 ， 可 以 先 在 本 机 运行 : 


# cd kibana/src 
# python -mSimpleHTTPServer 


浏览 器 访问 http://localhost: 8000/， 看 到 的 就 是 Kibana 3 了 ! 


如 果 你 使 


好 入 数据 方面 ， 我 们 就 采 


# curl -XPUT http://localhost:9200/shakespeare -d ' 


t 
“mappings” : { 
" default " : { 
"properties" { 
“speaker” : { “type” : “string”, “index” "not analyzed" }, 
"play name" : { “type” : “string”, “index” "not analyzed" }, 
"line id' : ( "type" “integer” }, "s 
"speech number" : ( "type" "integer" } 
ii 
} 
} 
p 


# wget http://www.elasticsearch.org/guide/en/kibana/3.0/snippets/shakespeare.json 
# curl -XPUT localhost:9200/_bulk --data-binary @shakespeare.json 


在 准备 工作 中 ， 你 已 经 通过 访问 http://localhost: 8000/8&n& 


的 是 Windows 电 脑 ， 则 建议 安装 一 个 Nginx、Apache 服 务 器 软件 ， 将 kibanaysrc 目 录 作为 documentroot 发 布 即 可 。 人 生产 环境 的 部 署 细节 ， 本 章 稍 后 会 有 自 


之 前 章节 讲 过 的 批量 导入 方法 。 不 过 我 们 首先 通过 上 传 映射 的 方式 创建 索引 。 注 意 ， 这 里 设置 了 对 speaker 和 play_name 两 个 字段 不 分 词 : 


16-1 这 样 的 欢迎 界 


Ej 


只 十 


接 发 布 了 顶层 路 径 ， 再 次 提示 : 


„al Introduction 


TEXT 


EN dl 
kbana  : 


W you wero using fe ok! defaut page you might not be expecting 
Fis screen. | understand, change can be aakoward. Let me explain 


Setting a globel default dashboerd 


Kibana has always shipped with an mterfaoe for Logstash, stil 


does! You can access it 


However, Y vou went fo make f your 


发 布 src/ 目 录 。 


TEXT 


Requirements 
A good browser. 


A webeerver 


Welcome to Kibana. 


Glad you coukd make it. Happy to have you here! Lets get started, shall we? 


了 。 如 果 看 到 其 他 提示 页 


， 请 根据 


Ej 


Just eormewhene 10 host the HTML and JavascrpL Basically any webserver will work 


Elastiosearch 
0.90.9 or above 


Configuration 


dolau again. all you need ID do ia rename a flol In your bana 


natndabon directory 


I Kibana and Elasticeeanch ane on fe seme host, and youre t 


use fat setup by dotm sy 


Rename bogata json Yo deficit json and refreah Shoki be all vet 


But wait, there's more! 


Mn fact, you can add any exported dashboard to that directory and 


ooons it as AIDA YOUR-HOST 
HERE/An 


wick oh? 


x himilidashboard/fe^rOUR-DASHOONRD json. Neat 


导入 数据 的 命令 执行 完成 后 ， 点 击 图 


ff (ot, you need to edit config js and set Pa alas 


server Tho host part shoud ba the 


Are you a Logstash 
* YES 


Great! We have 


xut dashboard 


vani domain nme, or P, not looathost 


Sen the note to 


I don't have much data yet, please extract soma bascs fr me 


图 16-1 


! havo a Jot of dati and | don't want Kibana fo query it at once 


omfortaóle figuring (f out on my own 


Kibana 3 欢迎 您 


16-1 中 指明 位 置 的 Sample Dashboard 链 接 。 可 以 看 到 页 


区 域 块 ， 就 是 Kibana 3 最 迷人 的 可 视 化 功能 


面 变 成 了 


D 


16-2 中 的 样子 。 虽 然 还 是 有 大 段 的 文字 ， 但 新 出 现 的 另外 几 个 


ARNA. 


体 提示 内 容 调整 配置 。 最 常见 的 可 能 就 是 ， 从 GitHub 上 下 载 的 源码 包 ， 直 


The lateet version of Chrome or Frekox is necommendecd. Safari fatest version) and el Explorer 9 and above are also supported 


The defe A Elastceearch port, then you're all set. Kibana e configured fo 


^ parameter wit the URL Mading port, probably 9900) ot your Elaatiocseech 


trio right about making It your giobal default 


板 (panel) ， 即 一 个 页 面 的 


„añ Your Basic Dashboard 


Toggle query 


HAVE A TIMESTAMP SOMEWHERE? o t x ABOUT FILTERS o t x 


Wf you have a feld with a timestamp in R, you can set a fime fiter using the control in the navigation bar. Youl need to Soo the Fiters bar above? Click it to expand fe filters panel. Right now there are 
Click tha cog icon to configure tho field that your tmestamp is in. none. click on one of the icons in the document types list to Sitar down to only 
that document type 


THE MOST GENERIC DASHBOARD EVER o t x 


Ws the best | can do without knowing much about your datal Ive tried to pick some sane defaults for 
you. The two farms paneis to the left of this fex! panel show 8 breakdown of your document type 


Kibana is currently configured to point at the special Elasticssarch |. alf index. You can change that 
by clicking on the cog icon in the navigation bar at the top. You can also add rows from fat dialog. 
You can edit individual pansis by click on fhe cog icon on the panel you want to edt 


The table panel below has attempted to list your fields to fhe left, select a few to view them in fe 
table. To add more panels, of different types, click the cog on ho row label to fo far left 


0 to 100 of 500 matatio or paging 


| DOCUMENTS 


Fields Q -souroe (select columna from the list to the left) 
hoe f 5954, "cle. namoe"-*Henry VI Port 1*, speech, umbo”: 14, "ne. number*:* 5.4.00" "soeaker*:* JOAN LA PUCELLE", text, entry*: Thon, Joan, decovor thine infemity."] 
[Ire «P5047, 'pay name "Henry VI Part 1°, "speech numb 11, "ini normiber*: * 5.4.53" poske" JOAN LA PUCELLE", ‘hat entry: Wii cry for vengeance at the gates of heaven. ") 
[ineo «f 5042, "cler ume" Hony VI Part 1*, "speech aurmibir* 11," nunmier*:* 5.4 48" poar": JOAN LA PUCELLE”, "hat entry”: To compass wonders but by help of devis." 


line. f-5040." ci. name Honey VI Par 1*,"soeach. number*:11,*ine. number 55.4.48". " sped": JOAN LA PUCELLE", "text. entrv*: Because vou want the aace that others hava, "| 
E]16-2 sample fU di 
这 里 最 显眼 的 无 疑 是 左 侧 的 饼 图 。 这 里 显示 的 是 你 的 索引 中 ， 文 档 类 型 的 排序 情况 。 示 例 中 ，99% 都 是 lines， 只 有 少量 的 acts 和 scenes。 具 体 值 在 其 右 侧 的 表格 中 也 可 以 可 看 到 。 
底部 是 一 个 大 表格 ， 可 以 看 到 我 们 之 前 导入 的 水 士 比 亚 诗歌 的 具体 内 容 。 
1. 搜 索 功能 


Sample Dashboard 顶 ， 有 一 个 长 条 的 搜索 框 ， 如 图 16-3 所 示 。 这 里 我 们 可 以 使 用 Lucene Query String 语 法 搜索 Elasticsearch 中 的 数据 。 


o 
- n o + 


vsum mu a Sarra far :av ha evird in ha nimiin har Varl essent nN 


图 16-3 Query 框 位 置 


一 下 在 请 求 框 中 输入 “friends，romans，countrymen” ， 回 车 ， 然 后 查看 表格 中 的 前 几 行内 容 。 如 图 16-4 所 示 ， 表 格 内容 刷 新 后 ， 显 示 的 新 内 容 都 命中 了 我 们 搜索 的 单词 。 


0 to 100 of 500 wminba tx grg 


sourve (emot colons bom the let to the bf) ME. 


lire f 47871, pln ^v AAA Coe" "npe suni 20, "nie iunt 0:2: 80 "iom" " ANTONIN "uet. entry! "Fondi, Parara, oounteynmen. ied me your eam; 
rw if 47WOD "pie ^m^ T 3 A'* "poe" "ORD ar TWO oyra, ww Puer me or YY 
Fiw kf 38512, py "wrno* "rhervy V pch arta 1, "ire nur 74.0 34" paar "Ohorus "wet, entry" Ard cala Pam bycewm Vends and ariran " 

"ine. kf 00477 "pis, armo "Thus Andronicus "wpiech. nunt" 2, "Ine. nurmber *1 71 07, "apart: RAGERANUS" "test. ent Romerm fienda. baower fevories of my gt 


Ine, if £297 1 "ph ime" "Merchant of Venice" "soeech. number*:28. "ime number" *3.2 poa "RAGISANIO" "rest, entry: ^t euo my very fienda and oountmyemen, *] 


图 16-4 表格 内 容 


2. 配 置 索引 模式 


现 有 仪表 盘 上 单纯 的 操作 大 致 就 是 这 样 ， 非 常 简单 。 但 是 当 你 真 要 处 理 自己 通过 Logstash 导 入 的 日 志 数 据 时 ， 可 能 你 的 第 一 个 问题 会 是 : 我 怎么 知道 Kibana 会 读 取 哪 个 索引 里 的 内 容 ” 或 者 说 ， 怎 么 才 
能 限制 Kibana 只 读 取 某 个 索引 的 内 容 ? 


对 这 个 需求 ，Kibana 设 计 了 索引 模式 (index pattern) 。 可 以 在 仪表 盘 配 置 中 修改 。 点 击 右 上 角 的 配置 按钮 ， 如 图 16-5 所 示 。 


弹出 的 配置 页 浮 层 如 图 16-6 所 示 。 可 以 看 到 ， 我 们 正在 用 的 这 个 simple dashboard， 指 向 了 Elasticsearch 一 个 特殊 的 索引 叫 _all。_all 可 以 理解 为 全 部 索引 的 大 集合 。 这 里 可 以 修改 成 任意 其 他 索引 名 。 


你 也 可 以 选择 左 侧 Timestamping 下 拉 菜 单 中 的 “Day”， 然 后 输入 [logstash-]YYYY.MM.DD， 这 样 ，Kibana 会 自动 生成 对 应 的 索引 名 供 使 用 ， 比 如 logstash-2015.07.23。 
欢迎 页 上 点 击 的 不 是 simple dashboard 而 是 logstash dashboard， 其 配置 的 索引 模式 真是 如 此 ! 


有 实 上 ， 如 果 你 在 最 开始 


„aÑ Your Basic Dashboard 


HAVE A TIMESTAMP SOMEWHERE? o + x ABOUT FILTERS o 中 x 


F you have a lioki with a now in it, you can set a Dre filter using the control in fe navigation bar Soo the Filters bar above? Click 9 10 expand me fter panel. Fig 
You'll need to click the cog icon to configure the fekd that your timestamp is in Now Then ane none. cic on one of the icons in fhe document typen fiet 


to ftor down to only that document type 


图 16-5 ”全 局 设置 按钮 


Dashboard Settings 


图 16-6 ”索引 模式 配置 


在 Elasticsearch 发 布 1.4 版 后 ， 使 用 Kibana 3 访问 Elasticsearch 1.4 集 群 ， 会 显示 如 图 16-7 所 示 的 错误 信息 。 


Connection Failed 


Possibility #1: Your elasticsearch server Is down or unreachable 


This can be caused by a network outage, or a tadiure of the Elasbcsearc If you have recently run a query that required a terms fac 9 executed it is possible the process 
has run out of memory and stopped. Be sure to check your Elasticsearch logs for any sign of memory pressure 


Possibility £2: You are running Elasticsearch 1.4 or higher 


Elasticsearch 1.4 ships with curity sefting that prevents Kibana from connecting. You will need to set the follaweng In your etasticsearch ym 


1. http.cors.enabfed. true 
2 http. cors aliow-onjgin to the correct protocol, hostname, and port (if not 80) that your access Kibana from. Note that if you are running Kibana in a sub-urt, you shouM exclude the subd- 
urt path and only include the protocol, hostname and port. For example, http mycomparry.com:8080, not htlpmycompany.com:8050/bana 


Click back, or the home button, when you have resolved the connection issue 


图 16-7 安全 提示 


这 是 因为 Elasticsearch 1.4 增 强 了 权限 管理 。 你 需要 在 Elasticsearch 配 置 文件 elasticsearch.yml 中 添加 下 列 配 置 并 重启 服务 后 才能 正常 访问 : 


http.cors.enabled: true 
http.cors.allow-origin: “*” 


记 住 Kibana 3 页 面 也 要 刷新 缓存 才 行 。 


此 外 ， 如 果 你 可 以 很 明确 自己 Kibana 以 外 没有 其 他 产品 通过 HTTP 接 口 访问 Elasticsearch 的 ， 可 以 把 Kibana 的 网 址 写 在 http.cors.allow-origin 参 数 的 值 中 ， 做 到 更 严格 的 控制 。 比 如 : 


http.cors.allow-origin: “/https? :\/\/kbndomain/” 


config,js 是 Kibana 核 心 配 置 的 地 方 。 也 是 唯一 不 能 在 运行 以 后 页 面 修改 的 配置 内 容 。 所 以 ， 文 件 里 包括 的 参数 都 必须 在 运行 Kibana 之 前 提前 设置 好 。 尤 其 是 在 把 Kibana 从 自己 个 人 电脑 搬 上 生产 环境 


的 时 候 ， 一 定 会 需要 修改 这 里 的 配置 。 下 面 介 绍 几 个 最 常见 的 修改 项 。 


“ elasticsearch: 你 的 Elasticsearch 服 务 器 HTTP 接 口 的 URL 访 问 地 址 。 黑 认 这 里 会 尝试 访问 你 和 Kibana 服 务 同一 个 主机 名 服务 器 的 9200 端 口 。 如 果 生 产 环 境 ，Kibana 跟 Elasticsearch 是 分 别 部 署 的 ， 这 里 需 
修改 成 你 Elasticsearch 服 务 器 的 主机 名 。 如 果 你 要 传递 参数 给 HTTP 客 户 端 ， 这 里 也 可 以 设置 成 对 象形 式 ， 如 下 


elasticsearch: {server: "http://localhost:9200" , withCredentials: true) 


“ default route: 访问 没有 指明 加 载 哪个 仪表 盘 的 时 候 ， 默 认 加 载 页 路 径 的 设置 参数 。 简 单 的 说 ， 就 是 设置 哪个 仪表 盘 为 主页 。 可 以 设置 为 文件 ， 肢 本 或 者 保存 在 Elasticsearch 里 的 仪表 盘 。 具 体 区 别 本 章 
稍 后 讲述 。 比 如 ， 你 有 一 个 保存 成 “WebLogs” 的 仪表 盘 在 Elasticsearch 里 ， 想 设置 为 主页 ， 那 么 你 就 可 以 设置 成 : 


default route: /dashboard/elasticsearch/WebLogs, 


* kibana index: 用 来 保存 Kibana 相 关 对 象 (比如 仪表 盘 ) 的 Elasticsearch 索 引 的 名 称 。 默 认为 kibana-int。 


“ panel_name: 可 用 的 面板 模块 数组 。 面 板 只 有 在 仪表 盘 中 有 定义 时 才 会 被 真正 加 载 ， 这 个 数组 只 是 用 在 “add panel” 界 面 里 做 下 拉 菜 单 。 


之 前 说 过 ，Kibana 3 是 一 个 单 页 应 用 。 所 以 其 页 面 布局 设计 是 固定 的 。 顶 部 栏 作为 全 局 设置 ， 接 下 来 是 全 局 Query 栏 ， 全 局 Filtering 栏 ， 以 及 具体 可 视 化 图 表 的 部 分 。 


本 节 就 介绍 这 两 部 分 的 操作 方式 和 用 法 。 


D 


啊 ， 表 啊 ， 地 图 啊 ，Kibana 有 好 多 种 图 表 ， 我 们 怎么 控制 显示 在 这 些 图 表 上 的 数据 呢 ? 这 就 是 请 求 (query) 和 过 滤 (filtering) 起 作用 的 地 方 。Kibana 是 基于 Elasticsearch 的 ， 所 以 支持 强大 的 
Lucene Query String 语 法 ， 同 样 还 能 用 上 Elasticsearch 的 过 滤器 能 力 。 


还 是 用 之 前 入 门 章节 我 们 导入 的 莎士比亚 数据 集 举 例 。 这 次 我 们 不 用 那个 最 简单 的 simple dashboard 了 。 官方 提供 了 另 一 个 更 漂亮 的 仪表 盘 ， 如 图 16-8 所 示 。 想 要 在 本 机 复 现 该 仪表 盘 的 读者 ， 可 以 查 
阅 稍 后 16.5 节 。 


~ Plays by Line Count 


O to 100 of 500 avadnbio for pagng 


* iho number > * text entry 
4331 So are the horses of tho enemy 
4.3.24 That you foreeee not what mpedments 
You, or tongi 
Do me no slander, Douglas: by my ife. 
His i cortan, ours i doubt 
HOTSPUR Why say you 907 looks he not for supply? 
FALSTAFF Enter HOTSPUR, WORCESTER, DOUGLAS, and VERNON 
FALSTAFF What, i5 the king encamped? 
FALSTAFF that; and for thor bereneos, ! am sure hoy nevor 


WESTMORELAND and bare, too beggery 


PRINCE HENRY | dd never soe such pul rascals. 


图 16-8 AU dcm tl 


依然 是 搜索 ， 这 次 搜 一 个 莎士比亚 最 有 名 的 句子 : 


to be or not to be 


AR, REER PRXEAIRHHEBRS (CARE). PAFTA (58--— A) RESE, REA "to be”， 也 没有 “not to be”。 事 实 上 ， 这 里 匹配 上 的 是 to OR be OR or OR not OR to 
OR be, 


实际 上 ， 应 该 是 加 双 引号 来 匹配 整个 短语 : 


"to be or not to be" 


更 多 搜索 语法 ， 在 本 书 之 前 Elasticsearch 部 分 已 经 有 详细 解释 ， 这 里 不 再 重复 。 


多 个 


有 些 场 景 ， 你 可 能 想 要 比 对 两 个 不 同 请 求 的 结果 。Kibana 可 以 通过 OR 的 方式 把 多 个 请 求 连接 起 来 ， 然 后 分 别 进行 可 视 化 处 理 。 


添加 请 求 的 方法 如 图 16-9 所 示 ， 点 击 请 求 输入 框 右 侧 的 + 号 ， 即 可 添加 一 个 新 的 请 求 框 。 


16-9 添加 多 个 请 求 的 按键 位 置 


PLAYS BY LINE COUNT 


5000 


4000 — 
3000 一 -一 - 
2000 


在 左边 绿色 输入 框 ， 输 入 “to be" ; 然后 右边 黄色 输入 框 ， 输 入 “not to be”。 这 就 会 搜索 每 个 包含 有 “to be” 或 者 “not to be” 内 容 的 文档 ， 然 后 显示 在 我 们 的 hits 饼 图 上 。 我 们 可 以 看 到 原先 一 
个 大 大 的 绿色 圆 形变 成 图 16-11 这 样 。 


图 16-10 ”多 个 Query 框 


PLAYS BY LINE COUNT 


图 16-11 ”多 Query 对 应 面板 


要 移 除 一 个 请 求 ， 移 动 鼠 标 到 这 个 请 求 输入 框 上 ， 然 后 会 出 现 一 个 x 小 图 标 ， 点 击 小 图 标 即 可 。 如 图 16-12 所 示 。 


[ 


@ "not to be" 


图 16-12” 移 除 Query 按 键 位 置 


Kibana 会 自动 给 你 的 请 求 分 配 一 个 可 用 的 颜色 ， 你 也 可 以 手动 设置 颜色 。 点 击 请 求 框 左 侧 的 彩色 圆 点 ， 就 可 以 弹出 请 求 设置 下 拉 框 。 这 里 面 可 以 修改 请 求 的 颜色 ， 或 者 为 这 个 请 求 设置 一 个 新 的 图 例文 
字 ， 如 图 16-13 所 示 。 


„añ Plays by Line Count 


图 16-13 ”颜色 和 图 例 


很 多 Kibana 图 表 都 是 交互 式 的 ， 可 以 用 来 过 滤 你 的 数据 视图 。 比 如 ， 点 击 你 图 表 上 的 第 一 个 条 带 ， 你 会 看 到 一 些 变动 。 整 个 图 变 成 了 一 个 大 大 的 绿色 条 带 。 这 是 因为 点 击 的 时 候 ， 就 添加 了 一 个 过 滤 规 
则 ， 要 求 匹配 play_name 字 段 里 的 单词 。 


你 要 问 了 “在 哪里 过 滤 了 ”? 


答案 就 藏 在 图 16-14 所 示 过 滤 (FILTERING) 标签 上 出 现 的 白色 小 星星 里 。 点 击 这 个 标签 ， 变 成 图 16-15 的 样子 。 你 会 发 现在 FILTERING 面 板 里 已 经 添加 了 一 个 过 滤 规 则 。 在 FILTERING 面 板 里 ， 可 以 添 
加 、 编 辑 、 固 定 、 删 除 任意 过 滤 规 则 。 很 多 面板 都 支持 添加 过 滤 规 则 ， 包 括 表格 (table). HAE (histogram) 、 地 图 (map) 等 等 。 


-a Plays by Line Count 
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piy name ` apeskur ， 

A Comed of Errors DROMIO OF SYRACUSE 
A Comady of Enom OF SYRACUSE 

A Comedy of Emors DROMIO OF SYRACUSE 


A Comedy of Erom OF SYRACUSE 
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! Ane number > text entry 
long, | rust get à onoo for my hoad end ensconoe 
F you wil pet with me, know my apaci 
ANTIPHOLUS 


Yea, dost fou eer and fout e n fe teet? 


图 16-14 ftering 白 色 小 星星 


如 图 16-15 箭 头 所 指 ， 过 滤 规 则 也 可 以 自己 点 击 + 号 手动 添加 。 


Kibana 仪 表盘 的 可 视 化 图 标 部 分 是 由 行 (row) 和 面板 (panel) 组 成 的 。 这 些 都 可 以 随意 的 添加 ， 删 除 和 慎 


图 16-15 展开 的 filtering 


M 
En 


从 主屏 里 选择 第 三 项 ， 就 会 加 载 一 个 空 


仪表 盘 (Blank Dashboard) 。 默 认 情况 下 ， 空 


Kibana 3 入 门 中 介绍 。 


仪表 盘 也 会 搜索 Elasticsearch 的 _all 索 引 ， 也 就 是 你 的 全 部 索引 。 要 指定 搜索 某 个 索引 的 方法 ,已 在 16.1 节 


„ali Introduction 


TEXT 


EM d 
Hana __ 


M yon woro using ho ok dofadt page you might not bo 
expecteg tha sorsan. undanta, change can be 
ivicward. Let me explan 


Setting a globe! default deshboerd 


Kibanae has sways tipped with an toface tor 


Logstash, still does! You can accen it However, it 


yo want qo male it you Galai aguin, all you oed to 
do is rename a filol In your dana nstullabon directory 


Fonarme fogstash son 加 default. json arn retresih 
Should be al set 


But wait, there's morel 


In fact, you can add ary exported dashboard t that 
drectory and access it as hip /YOUR-HOST 
HERE/(idex himificiashbóooero Tie rOUR 
DASHBOARD json. Neet trick eh? 


2. 添 加 一 行 


空白 仪表 盘 上 只 有 展开 的 请 求 和 


-<m New Dashboard 


滤 区 域 ， 页 面 顶 栏 上 有 个 时 


TEXT 


Welcome to Kibana. 


Glad you codd make it. Happy to have you here! Lets ge! started, shall we? 


Requirements 

* A good browser. 
Tho latest version ol Chrome or Firefox is recommended. Salari (atest version) and ietenet Explore O and above 
are also supported 

* A wobsoerver. 
Just somewhere to host fe HTML and Javascript. Basically any webassnver will work 

* Elasticsoarch 
0.90.0 o above 


Configuration 


If Kibana and Elasticseearch are on the seme host, and you're using the default Elasticsearch por, hon you're all set 
Kibana is configured To use that setup by detti 


M cot, you eed bo edit corn arxi sot foo elmsticsewrcfh paramotor with ho UFE Qnchkading port, probably 8200) of 


your Elsbcsearch server. The host part should be the entro, fuly qualifiec domain name, o IP, not localhost 
Are you a Logstash User? 


* YES - Great! We have a prebult dashboard 
gicbal dotad 


See the note to the night about making it your 


* NO - Hey, no problem, you just have a bit of setup fo do. You have a fw choices 


1 Idon'thave much data yet, please extract some basics for me 
Ihave a lot of data and | dont want Kibana fo query it at once 
lm comiortabio figuring it out on my own 


图 16-16 进入 空白 页 的 链接 位 置 


选择 器 ， 除 此 以 外 什么 都 没有 。 如 图 16-17 所 示 ， 在 仪表 盘 右 下 方 ， 点 击 添加 行 (ADD A ROW) 按钮 ， 添 加 你 的 第 一 行 。 


图 16-17 加 row 的 按键 位 置 


设置 界面 如 图 16-18 所 示 。 给 这 个 行 取 个 名 字 ， 然 后 点 击 创建 (Create Row) 按钮 。 你 会 看 到 新 行 出 现在 左 侧 的 行列 表 里 。 点 击 保存 (Save). 


Dashboard Settings 


图 16-18 ”添加 row 的 设置 界面 


如 图 16-19 所 示 ， 现 在 你 有 了 一 行 ， 你 会 注意 到 仪表 盘 上 多 了 点 新 元 素 。 


这 三 个 按钮 是 让 你 做 这 三 件 事情 的 : 


1) H7 ( 蓝 色 ) 


2) 配置 行 ( 橘 色 ) 


3) 添加 面板 (绿色 ) 


要 是 左 侧 多 出 来 的 三 个 小 小 的 不 同 颜色 的 长 方形 。 移 动 鼠 标 到 它们 上 面 。 就 可 以 看 到 如 图 16-20 所 示 的 三 个 按钮 从 左 侧 弹出 ， 


图 16-19 ”空白 的 tow 


16-20 ”展开 的 row 操 作 按 键 菜单 


我 们 先 来 试 试行 控制 里 的 绿色 按钮 ， 点 击 它 ， 可 以 看 到 如 


b 可 以 点 击 空白 行内 的 灰色 按钮 (Add panel to empty row) ， 同 样 会 看 到 这 个 界面 。 不 过 这 个 灰色 按钮 只 有 在 行内 


一 个 面板 都 没有 的 时 候 才 可 见 ， 所 以 最 好 还 是 统一 使 


bettermap 
Column 
goal 
histogram 
hits 

map 
sparklines 


stats 


table 


作为 最 常用 的 功能 ， 这 里 演示 添加 一 个 terms 面 板 。terms 


如 图 16-22 所 示 ， 你 可 以 看 到 ，terms 面 板 有 一 系列 可 配置 选项 ， 不 过 我 们 


图 16-21 ”添加 panel 的 选项 


上 Elasticsearch 的 terms facet 功 能 ， 查 找 一 个 字段 内 最 经 常 出 现 的 几 个 值 。 


只 管 第 一 段 里 的 通用 配置 好 了 ， 各 面板 独 有 的 详细 配置 ， 本 书 稍 后 16.4 节 会 专门 讲解 。 下 面 介绍 面板 选项 。 


Row Settings 


Stable // Omplays fw rents of an elasSceearch feoet an a pie chart, bar chart, or a table 
Tite Span Editable repect © 


Parameters 


Tora mode Exchado Torrmmis) (oormma separated) 


Legen. Formar Missing Other 


16-22 terms 面 板 选项 


"Tile: 面板 的 名 称 。 
“ Span: 面板 的 宽度 。Kibana 仪 表盘 等 分 成 12 个 spans 面 板 最 大 就 是 到 12 个 spans 宽 。 但 是 行 可 以 容纳 超过 12 个 spans 的 总 宽度 ， 因 为 它 会 自动 把 新 的 面板 放 到 下 面 显示 。 现 在 我 们 先 设置 为 4。 
` Editable: 面板 是 否 在 之 后 可 以 继续 被 编辑 。 


“ Inspectable: 面板 是 否 允 许 用 户 查看 所 用 的 请 求 内 容 。 


点 击 Save 添 加 这 个 新 terms 面 板 到 仪表 盘 。 效 果 如 


16-23 所 示 。 


D 


nm 有 New Dashboard 


No filters available 
o 


TYPES OF DOCUMENTS O 9 ^ x 


€ ine (110487) € scene (729) € act (180) 
€ dashboard (1) € Missing field (0) Other values (0) 
150000 


100000 


图 16-23  3X&panel 44 BL AT] 
面板 宽度 也 可 以 在 仪表 盘 内 直接 拖 搜 修 改 ， 将 鼠标 移动 至 面板 左 (A) 侧 边线 处 ， 鼠 标 会 变 成 相应 的 箭头 ， 按 住 左 键 拖 搜 成 满意 宽度 松 开 即 可 。 
5. 折 县 和 展开 行 


返回 再 看 一 次 图 16-20 里 其 他 的 按钮 。 蓝 色 按钮 可 以 折 双 你 的 行 。 被 折 硬 行 里 的 面板 不 会 刷新 数据 ， 也 就 不 要 求 Elasticsearch 资 源 。 所 以 折 码 行 可 以 用 于 那些 你 不 需要 经 常 看 的 数据 。 有 需要 的 时 候 点 
击 蓝 色 按钮 展开 就 可 以 了 ， 如 图 16-24 所 示 。 


节 讲 过 的 项 部 请 求 和 过 滤 区 域 也 可 以 被 折 双 。 点 击 彩色 标签 就 可 以 折 双 和 展开 ， 如 图 16-25 所 示 。 
6 编辑 行 


通过 行 编辑 器 ， 可 以 给 行 重 命名 ， 改 行 高 等 其 他 配置 。 点 击 栖 色 按钮 打开 行 编辑 器 。 弹 出 浮 层 效果 如 图 16-26 所 示 。 


„al New Dashboard 


图 16-24 折 有 的 行 


„ai New Dashboard 


这 个 对 话 框 还 允许 你 修改 面板 的 排序 和 大 小 ， 以 及 


7. 移 动 和 删除 面板 


出 除 面板 ， 如 


16-27 所 示 。 


面板 可 以 在 本 行 ， 甚 至 其 他 行 之 间 任 意 拖 搜 。 按 住 面 板 右上 角 的 十 字 架 形状 小 


图 16-25 折 胎 的 请 求 过 滤 条 


图 16-26 ” 行 编辑 器 


标 然后 拖 动 即 可 ， 效 果 如 图 16-28 所 示 。 


Span (12/12 


图 16-27 行 编辑 器 里 的 面板 


Row Settings 


New Dashboard 


TYPES OF DOCUMENTS o o9 t x TERMS 


© 9 t 


eser qur oed Q9 Romeo (651) 


Q Juliet (588) 


Drop here to add to this row 


Or drop on top of any other panel to insert in that row 


图 16-28 4&5) Ped E 
如 图 16-29 所 示 ， 点 击 面板 右上 角 的 X 小 图 标 就 可 以 从 仪表 盘 上 移 除 它 。 或 者 如 图 16-27 所 示 ， 从 行 编辑 器 上 也 同样 可 以 移 除 面板 。 
8. 移 动 和 删除 行 
行 可 以 在 仪表 盘 配置 页 中 重新 排序 和 删除 。 点 击 屏幕 右上 角 的 配置 按钮 ， 选 择 行 (Rows) 标签 切换 到 行 配置 层 ， 如 图 16-30 所 示 。 看 到 这 里 你 一 定 会 记 起 来 我 们 在 添加 第 一 个 行 时 候 的 屏幕 。 


左 侧 的 箭头 用 来 修改 仪表 盘 上 行 的 次 序 。X 用 来 删除 行 。 


TYPES OF DOCUMENTS o0 ù + x 


€ ine (110487) € scene (729) € act (180) 
€ dashboard (1) € Missing field (0) Other values (0) 
150000 


100000 à; 
50000 
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rom Dashboard Settings 


图 16-29 面板 删除 小 图 标 


Tite 
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图 16-30 BL dE p 854 


164 各 面板 功能 


Kibana 3 仪表 盘 由 面板 (panel) 块 组 成 。 面 板 在 行 中 可 以 起 到 很 多 作用 ， 不 过 大 多 数 面 板 是 用 来 给 一 个 或 者 多 个 请 求 的 数据 集结 果 做 可 视 化 。 剩 下 一 些 面板 则 用 来 展示 数据 集 或 者 用 来 为 使 用 者 提供 
插入 指令 的 地 方 。 


面板 可 以 很 容易 地 通过 Kibana 网 页 界面 配置 。 而 有 些 不 起 眼 的 选项 ， 可 能 在 不 同 场景 下 有 自己 独特 的 作用 。 本 节 主 要 会 针对 各 面板 的 配置 项 ， 展 示 其 细节 效果 和 场景 用 途 。 


此 外 ， 为 了 配合 接 下 来 的 仪表 盘 纲 要 介绍 ， 每 节 面 板 介绍 后 面 ， 会 附带 这 个 面板 在 仪表 盘 纲 要 中 的 可 定义 属性 列表 。 这 点 在 你 使 用 模板 化 或 者 脚本 化 仪表 盘 功 能 时 ， 或 许 有 用 ， 因 为 纲要 中 一 些 隐藏 属 
性 是 通过 网 页 界面 看 不 到 的 设置 项 。 


此 外 ， 虽 然 每 个 面板 类 型 都 有 自己 的 属性 ， 不 过 有 这 么 几 个 属性 是 大 家 共有 的 ， 之 前 行 与 面板 小 节 就 提 到 过 ， 后 面 就 不 再 一 一 重复 了 : 


` span: 一 个 从 1~12 的 数字 ， 描 述 面板 宽度 。 


“ editable: 是 否 在 面板 上 显示 编辑 按钮 。 


“ type: 本 对 象 包含 的 面板 类 型 。 每 个 具体 的 面板 类 型 又 要 求 添加 新 的 属性 ， 上 有 具体 列表 说 明 稍 后 详 述 。 


再 次 强调 ， 本 节 介绍 基于 我 的 https://github.com/chenryn/kibana.git 分 支 ， 其 中 有 十 多 处 增强 功能 式 的 扩展 。 读 者 如 果 发 现 操作 介绍 中 内 容 在 


ES 


上 找 不 到 的 ， 可 以 尝试 替换 我 的 版 本 。 


histogram 面 板 用 以 显示 时 间 序 列 图 。 它 包括 好 几 种 模式 和 变种 ， 用 以 显示 时 间 的 计数 ， 平 均 数 、 最 大 值 、 最 小 值 ， 以 及 数值 字段 的 和 ， 计 数 器 字段 的 导数 。 


添加 面板 的 方式 在 16.3.2 节 行 和 面板 中 已 经 有 过 讲解 。 在 Add panel 对 话 框 选择 类 型 为 histogram 后 ， 你 会 看 到 一 系列 可 配置 的 选项 ， 如 图 16-31 所 示 。 


Select Panel Type 


histogram * | Note: This row is full, new panels wil wrap to a new line. You should add another row. 


Stable // A Ducketed time series chart of the current query or queries. Uses the Elasticsearcn date histogram facet. If using time stan 
possible load to your Elasticsearch cluster 
Editable Inspect 6€ 


v v] 


Transform Series Time Options 
Seconds Q Derivative @ Zero fill @ Time Field Time correction — Auto-interva! Resolution @ 


& L e Gtimestamp browser $ & 100 


Chart Options Multiple Series 
Bars Lines Points Selectable xAxis yAxis Y Format Ọ Stack Percent Q Stacked Values © 


[v Ivi v] v none v B cumulati 


Legend Grid 
Zoom View Legend Query @ Counts Min / Auto 


v v v v V 0 


Queries 


图 16-31 histogram panel 的 设置 界面 


选项 分 为 四 类 ， 可 以 在 添加 之 后 ， 通 过 点 击 面板 右上 角 的 配置 Configure 小 图 标 弹出 浮 层 继续 修改 。 有 如 下 几 项 配置 : 


Histogram Settings 


Stable // A bucketed time series chart of the current query or queries. Usss tha Flasticsearch date histogram 
facet. If using time stamped indices this panel will query them sequentially to attemot to apply the lighest 


possible load to your Elasticsearch cluster 
Editable Inspect € 


T 


416-32 ”通用 配置 


“ 通用 (Genera) 配置 。 主 要 用 来 修改 面板 的 标题 和 宽度 ， 如 图 16-32 所 示 。 


“面板 (Panel) 配置 。 设 置 面板 向 Elasticsearch 发 出 何 种 请 求 ， 以 及 请 求 中 需要 使 用 的 变量 。 


板 中 ， 经 常用 的 Chart value ( 即 之 前 参数 部 分 描述 的 mode) 有 : 


如 图 16-33 所 示 ， 在 histogram 面 


Histogram Settings 


Transform Series 
Seconds Q Derivative Q Zero fill © 
e ® a 


Time Options 


Time Field Time correction — Auto-interval Resolution 6€ 


timestamp browser $ O 100 


图 16-33 面板 配置 
count。 最 常见 场景 就 是 统计 请 求 数 。 这 种 时 候 只 需要 提供 一 个 在 Elasticsearch 中 是 时 间 类 型 的 字段 ( 即 参 数 部 分 描述 的 time_field) 即 可 。 一 般 来 说 ， 都 是 @timestampb， 所 以 不 用 修改 了 。 这 也 是 默认 


的 Logstash 仪 表盘 的 基础 面板 的 样式 。 


' mean。 最 常见 场景 就 是 统计 平均 时 间 。 这 时 候 配置 浮 层 会 变 成 图 16-34 中 的 样子 。 


Histogram Settings 


Transform Series 
Chart value Value Field 9 Scale Seconds Q Derivative Q — Zero fill € 


mean s h5 view loadtime 1 e e v] 


Time Options 
Time Field Time comection — Auto-interval Resolution 全 


Qtmestamp browser v © 100 


图 16-34 mean 求 值 的 设置 
这 里 就 需要 提供 一 个 在 Elasticsearch 中 是 数值 类 型 的 字段 ( 即 参 数 部 分 描述 的 value_field) 作为 计算 平均 值 的 数据 集 来 源 了 。 以 Nginx 访 问 日 志 为 例 ， 这 里 就 填 “request time" , 


如 果 你 在 Logstash 中 使 用 的 是 %{NUMBER: request time}， 那 么 实际 类 型 还 是 字符 串 (请 记 住 ， 正 则 捕获 是 String 类 的 方法 ， 也 只 能 生成 String 结 果 ) ,必须 写成 %{NUMBER: request time: 
float} 强 制 转换 才 行 。 否 则 ， 你 会 看 到 如 图 16-35 所 示 报 错 信 息 。 


60 Oops! 
ClassCastException[org.elasticsearch.index fielddata. plain. PagedBytesIndexFieldData 
cannot be cast to org.elasticsearch.index fielddata IndexNumericFieldData] 


DDD O 29 ^ x 


ew > | Q Zoom Out | body bytes sent total per 30m | (0 hits) 


图 16-35 ”字段 类 型 错误 
“ total。 最 常见 场景 就 是 统计 带宽 。 配 置 界面 和 mean 是 一 样 的 。 同 样 要 求 填写 数值 类 型 的 字段 名 ， 比 如 “bytes_sent”。 


带宽 在 习惯 上 会 换算 成 每 秒 数据 ， 但 是 通过 修改 interval 的 方式 来 求 每 秒 数据 ， 对 Elasticsearch 性 能 是 一 个 很 大 的 负担 ， 绘 制 出 来 的 图 形 也 太 过 密集 影响 美观 。 所 以 Kibana 提 供 了 另 一 种 方式 : 保持 
interval, 4ji&seconds, Kibana 会 自动 将 每 个 数值 除 以 间隔 秒 数 得 到 每 秒 数据 。 (count 也 可 以 这 样 ， 用 来 计算 qps 等 数据 ) 如 图 16-36 所 示 。 


iew = | Q Zcom Ow | © 苹果 (26940131) count ber 1s | (26930131 hits) 


i Bars (Lines @ Stack (Legend (interval 30m (aut y 


300 


图 16-36 ”每 秒 带 宽 


另 一 个 有 用 的 功能 ,假如 你 的 日 志 量 实在 太 大 ， 被 迫 采 用 抽样 日 志 的 方式 ， 可 以 在 Kibana 上 填写 Scale。 比 如 百 分 之 一 的 抽样 日 志 ，Scale 框 就 写 100， 带 宽 数 据 就 会 在 展示 的 时 候 自 动 翻 100 倍 显示 出 
来 ， 如 图 16-37 所 示 。 


haus -| Q Zoom Ox | © 3, (26934455). count per 1s | (26034455 hits) 


ü Bars (Lines @ Stack (Legend (interval 30m (aut $ 


30000 


:uniq。Elasticsearch 从 1.1 版 本 开始 通过 HyperLogLog++ 算 法 支持 去 重 统计 聚合 。 在 我 的 fo 全 中 ， 用 Aggregation APT 5j histogram panel 后 ， 也 可 以 支持 了 ， 如 图 16-38 所 示 。 


Value Field © 


clientip.raw 


图 16-38 uniq 配 置 


常用 场景 比如 : UV 统计 ， 效 果 如 图 16-39 所 示 。 


; | Q zoom Out | € (440444263) clientip.raw uniq per 1s | (440444263 hits) 


图 16-39 UV 统计 


- 风格 (Style) 配置 。 如 图 16-40 所 示 ， 该 标签 页 用 于 设置 获取 的 数据 如 何 展现 。 其 中 小 部 分 选项 ， 即 条 带 (Bar) 、 折 线 (Lines) 、 散 点 (Points) ， 可 以 直接 在 面板 左上 角 的 “View” 下 拉 菜 单 里 直接 


匀 选 ， 如 图 16-41 所 示 。 


Chart Options 
Bars Lines Points Selectable xAxis yAxis Line Fill Line Width Y Format © 


LJ &e v vV v 


Header Legend Grid 


Zoom View Legend Query @ Counts Min / 


v v] v © v 1 


图 16-40 ”风格 设置 


首页 平均 响应 时 间 走 势 
| 6 H5 首 页 (4888571) h5 view loadtime mean per 30m | (4888571 hits) 
| Bars 已 Unes @ Stack (Legend Intervali 30m (aut $ 


2500 


M 


对 于 带宽 数据 ， 可 以 切换 Y Format 为 bytes。 则 Y 轴 数据 可 以 自动 换算 成 MB，GB 的 形式 ， 比 较 方便 ， 如 图 16-42 所 示 。 


图 16-41 view 小 菜单 


图 16-42 ”带宽 数据 单位 


此 外 ， 还 可 以 在 Grid 区 域 定义 Y 轴 的 起 始点 和 终点 的 具体 值 。 这 可 以 用 来 在 Y 轴 上 放大 部 分 区 域 ， 观 察 细微 变动 ; 或 者 忽略 某 些 异常 值 ， 如 图 16-43 所 示 。 注 意 ， 该 图 出 自我 fork 中 新 增 的 
valuehistogram 面 板 ， 去 除了 标准 histogram 面 板 的 X 轴 必须 为 时 间 字 段 的 限制 。 


如 果 面板 关联 了 多 个 请 求 ， 可 以 勾 选 以 堆 亚 (Stack) 方式 展示 (最 常见 的 堆 亚 展示 的 监控 数据 就 是 CPU 监控 ) ， 如 图 16-44 所 示 。 


堆 肢 的 另 一 种 形式 是 百分比 ， 如 图 16-45。 在 勾 选 Stack 的 前 提 下 勾 选 Percent。 
效果 如 图 16-46。 注 意 : 百分比 是 A/ (A+B) 的 值 ， 而 不 是 A/B。 


首页 胸 应 时 间 概 率 分 布 
» view| € H5 首 页 (5621418) count per 200 | 5621418 rits) 
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| I iiim A 
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16-43  valuehistogram 47 Y $h RI 4r] 


6 type:h5 view. log AND h5 view. platfo @ type:h5 view log AND h5 view r Q + 


TOP5 终 端 请 求 数 趋势 


view » | Q Zoom Out | 9 苹果 (26950425) @ 安 卓 (58979920) count per 1s | (85930345 hits) 
1000 


图 16-44 AROR 


Multipie Series 
Stack | Percent @ Stacked Values 0 


v v individua < 


H16-45 百分比 设置 


@ type:h5 view log AND h5 view. platfo @ type:h5 view log AND h5 view r Q + 


TOP5 终 端 请 求 数 趋势 


View» | Q Zoom Out | 6 苹果 (26950425) @ 安 卓 (58979920) count per 1s | (85930345 hits) 
100 


H16-46 百分比 效果 


“ 关联 请 求 (Queries) 配置 。 默 认 的 Queries 方 式 是 al。 可 以 使 用 selected 方 式 ， 在 右 侧 选 择 具体 的 请 求 框 〈 可 多 选 ) 。 被 选中 的 会 出 现 边 框 加 粗放 大 效果 ， 如 图 16-47 所 示 。 


多 请 求 的 默认 效果 如 图 16-48 所 示 。 而 堆 琶 和 百分比 效果 ， 在 之 前 已 经 谈 过 。 可 以 对 比 上 下 两 图 的 Y 轴 刻度 。 


Queries Selected Queries 


E 


selected 3 


Markers 


Here you can specify a query to be plotted on your chart as a marker. Hovering over a marker will display the fielc 
query will be displayed. 


Enable 


16-47 selected queries 


6 type:h5 view log AND h5 view. platfo Q type:h5 view log AND h5 view r Q + 


TOP5 终 端 请 求 数 趋 势 


View» | Q Zoom Out | & 3&:R (26950534) @ 安 卓 (58977523) count per 1s | (85928057 hits) 
700 
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图 16-48 selected queries AH 4 zi 
2. 仪 表盘 纲要 属性 


和 上 面 讲 的 配置 项 一 一 对 应 的 是 在 仪表 盘 纲要 中 的 属性 设置 。 稍 后 章节 会 专门 介绍 仪表 盘 纲要 的 整体 组 成 ， 这 里 先 介绍 histogram 面 板 的 可 设置 属性 ， 如 表 16-1 所 示 。 


表 16-1 histogram 面 板 的 可 设置 属性 


E 性 说 明 
用 于 立轴 的 值 。 除 了 count 以 外 .其 他 mode 设置 都 要 求 定 义 value field 和 参数。 可 选 值 为 : 


"X count. mean. max. min. total. FÉ fork 中 新 增 了 一 个 可 选 值 为 wiq 
time field X 轴 字段 。 必 须 是 在 Elasticsearch 中 定义 为 时 间 类 型 的 字段 
value field 如 果 mode 设置 为 mean, max, min 或 者 total, Y 轴 字 段 。 必 须 是 数值 型 
x-axis ETER XA 
y-axis ETER Y$ 
scale 以 该 因子 规划 YY 轴 
y format 了 轴 数 值 格式 ， 可 选 : none, bytes, short 
auto int 是 天 自动 调整 间隔 
Tesolution 如 果 auto int 设 为 真 ，shoot for this many bars 
interval 如 果 auto int 设 为 俱 ， 用 这 个 值 化 间 隔 
intervals 在 View 选择 器 里 可 见 的 间隔 数组 。 比 如 [“auto”, '1s' , ‘5m’ ,，'3h，]， 这 是 绘图 参数 
lines 显示 折线 图 
fill 折线 图 的 区 域 填充 因子 . 从 1 到 10 
linewidth 折线 的 宽度 . 单位 为 像素 
points 在 图 上 明示 数据 点 
pointradius 数据 点 的 大 小 ,单位 为 像素 
bars gor etis 
stack NE EIE» 
spyable 明示 审核 图 标 
zoomlinks 最 示 Zoom Out 链接 
options 显示 快捷 的 view 选项 区 域 
legend gmat 
show_query 如 果 没 设 别 名 (alias)， 是 否 显示 请 求 
interactive 允许 点 击 拖 搜 进行 放大 
legend counts 在 图 例 上 显示 计数 
timezone 是 天 调整 成 浏览 器 时 区 。 可 选 值 为 : browser utc 
Percentage 把 工 轴 数据 显示 成 百分比 样式 。 仅 对 多 个 请 求 时 有 效 
zerofill 提高 折线 图 准确 度 ， 稍 微 消 耗 一 点 性 能 
derivative 在 义 轴 上 显示 该 点 数据 在 前 一 个 点 数据 上 变动 的 数值 
可 以 指定 一 个 请 求 的 结果 作为 标记 显示 在 图 上 。 比 如 说 ， 标 记 某 时 刻 部 署 代码 了 。 其中: 
annotate.enable: 是 否 显示 注释 ( 即 标记 ) 
annotate query: 标记 使 用 的 Lucene query. string 语法 请 求 
annotate annotatesize; 最 多 显示 多 少 标记 


annotate field. 显示 哪个 字段 
annotatesort; 数组 排序 ， 格 式 为 [fieldorder]. HEWN [ ' timestamp! , 'desc' ]. 这 是 一 
个 肉 部 参数 


D D D D LU 


ut 
3 


B 性 说 明 
[有 具 提示 ， 其 中 : 
口 tooltip.value type : 控制 tooltip FERH LELER, Tt: 独立 (individual) 还 是 累 
计 (cumulative) 
Q tooltip.query as alias; 如 果 没 设 别 名 (alias)， 是 天 显示 请 求 
grid YY 轴 的 最 大 值 和 最 小 值 。grid.min 是 Y 轴 的 最 小 值 : grid max 是 阅 轴 的 最 大 值 
这 个 对 象 描 述 该 面板 使 用 的 请 求 。 这 个 对 象 也 是 所 有 面板 (markdown 除外 ) 都 会 有 的 设置 
之 后 小 节 不 再 重复 。 其 中 : 
queries 4f $ O quenes.mode : 在 可 用 请 求 中 应 该 用 哪些 ? 可 设 选 项 有 : all. pinned, unpinned. selected. 
默认 是 all 
口 queries.ids: 如 果 设 为 selected 模式 ,具体 被 选 的 请 求 编 号 


tooltip 


16.4.2 table 


表格 面板 里 是 一 个 可 排序 的 分 页 文档 。 你 可 以 定义 需要 排列 哪些 字段 ， 并 且 还 提供 了 一 些 交 互 功 能 ， 比 如 执行 terms 聚 合 查询 。 


1. 界 面 配置 说 明 


table 和 histogram 面 板 ， 是 kibana 自 带 的 logstash dashboard 里 唯一 使 用 的 2 个 面板 ， 可 以 说 是 最 重要 和 常用 的 组 件 。 


然 重 要 ，table 面 板 的 可 配置 项 却 不 多 。 主 要 是 panel 和 paging 两 部 分 。 下 面 分 别 介 绍 。 


- panel: 如 图 16-49 所 示 ，panel 设 置 可 以 分 成 几 类 ， 其 中 比较 重要 和 有 用 的 是 : 


Opiions 


Header Sorting Sort 3 +) 


@timesta J 
r p h5 view api © h5 view |p ©  h5 view loadtim 
LocalTimo Q Time Field e m 


& gtimes D Highlighted Fields 


16-49 table paneli Æ 
“ 时 间 字 段 : Time Field 设 置 的 作用 ， 和 histogram 面 板 中 类 似 ， 主 要 是 帮助 Kibana 使 用 者 自动 转换 Elasticsearch 中 的 UTC 时 间 成 本 地 时 间 。 


: 裁剪 因子 : 和 Splunk 不 同 ，Kibana 在 显示 事件 字段 的 时 候 ， 侧 重 于 单行 显示 。 详 情 内 容 通过 点 击 具 体 某 行 向 下 展开 的 方式 参看 。 每 个 字段 在 屏幕 中 的 可 用 宽度 ， 就 会 通过 裁剪 因子 来 计算 。 如 图 16-50 
所 示 。 有 具体 计算 方式 见 之 前 官方 参数 说 明 部 分 。 
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2014-08-03T05:28: 17.0007 

1 

fmv. 1 Gw9T5unOo-yljOoYw 

logstasn-2014.09.03 

mweibo client downstream 

HUAWEI-HUAWEI G610-TOO  weibo 4.3.5 android android4.2.1 
cmnet 

211.140.5.111 


2em.sina.weibo.oxcoption.WoeibolOException: Invalid responso from server: HTTP/1.1 404 Not Found 


图 16-50 tablet RY ET 


- 字段 列表 : table 面 板 左 侧 ， 是 字段 列表 多 选区 域 。 字 段 分 为 _all 和 current 两 种 。_all 是 Kibana 通 过 Elasticsearch 的 _mapping API 直 接 获 取 的 索引 内 所 有 存在 过 的 字段 ; cutrrent 则 仅 显 示 table 匹 配 范围 内 的 数 


据 用 到 的 字段 。 


勾 选 字段 列表 中 某 个 字段 ， 该 字段 就 加 入 table 面 板 右 侧 的 表格 中 成 为 一 列 。 如 图 16-51 所 示 。 
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图 16-51 ZukTE 
字段 列表 中 ， 可 以 点 击 具 体 字段 ， 查 看 table 匹 配 范围 内 该 字段 数据 的 统计 和 排行 数据 的 小 面板 ， 如 图 16-52 所 示 。 


小 面板 上 虽然 只 显示 一 个 很 小 范围 内 ( 即 size pages， 默 认 是 500) 的 数据 统计 ， 但 是 点 击 小 面板 底部 的 TERMS 下 拉 菜 单 选项 ， 生 成 的 term panel 浮 层 数据 却 都 是 基于 整个 搜索 结果 的 。 这 部 分 的 内 容 


介绍 。 请 阅读 稍 后 16.4.5 节 “term” 


DATA HS 44^ rv 7 noy 


Q Q Micro Analysis of geoip.city name 
Value 


Beijing 
Guangzhou 
Fuzhou 
Shenzhen 
Nanjing 
Hefei 

Jinan 
Shanghei 


— 
* 


S mp wgosmsIEtm 


6 
5 
5 
4 
4 
4 
3 
3 


图 16-52 ”小 排序 面板 


排序: 设置 中 可 以 设置 一 个 默认 的 排序 字段 。 在 logstash dashboard 默 认 的 event table 中 ， 设 置 的 是 时 间 字段 @timestamp。 不 过 这 个 设置 ， 指 的 是 面板 加 载 的 时 候 ， 使 用 该 字段 排序 ， 实 际 你 可 以 在 表 头 任 
意 字段 名 上 单 击 ， 以 该 字段 的 值 来 临时 排序 。 如 图 16-53 所 示 ， 排 序 字段 会 在 表 头 本 列 字段 名 后 ， 出 现 一 个 小 三 角 图 标 ， 三 角 箭 头 朝 上 代表 升序 ， 反 之 降序 。 


h5 view, api > 4 h5 view Ip > 

20000174. pit 123.165.83.31 Android4.4.2 
20000174. pit 36.43.121.234 otrer 
20000174. pit 221.205.158.178 Other 
20000174. pit 117.184.185.46 other 
20000174. pit 202.106.55.226 other 
20000174. pit 202.106.55.226 other 
20000174_plt 121.2.75.176 iPhone50 
20000174. pit 121.32.24.163 


20000174 pit 202.106.55.226 


图 16-53 ”排序 


Kibana 中 也 同样 支持 解析 Elasticsearch 返 回 的 HTML 高 亮 文本 。 只 需要 在 panel 标 签 页 右 侧 添 加 Highlighted field， 在 搜索 框 里 填 入 的 关键 


段 列 表 中 色 选 ) ， 如 图 16-54 所 示 。 


, Windows 


0 to 20 cf 100 available for paging 


Fields @ m 


3) Current (32) web169.mwelbo.yf.sinanode.com(| unread|-00031]|1409623500583/|58.30.134. 15 REEE m other[Chrome|Chrome, 31.0. 1650.48 
Type to filter wrob163.mwolbo.yf.sinanodo.com| unroac]]-59820/1409498259606]66.222.223.23c II o nori cnromeicnroma_21.0.1180.91 


wretXo33.mwelbo.bx.sinanode.com| unrcant-59461]1409641364203]218.5.2.1 co ER ERMEomerionromejonrome. 21.011 80 91 


vreb110.mweibo.yt.sinanode.com|10000011. piti-12085/1409537731330,58.215.136 5 A orm quoquc. 9.9.2 467 


图 16-54 


高 亮 仅 在 table 状 态 有 效 ， 点 击 展开 后 的 事件 详情 中 是 不 


“ paging: 考虑 到 同时 展示 太 多 内 容 ， 一 来 对 Elasticsearch 压 力 较 大 ， 二 来 影响 页 面 展 示 效 果 生 能 。Table 面 板 设计 了 翻 页 查看 的 模式 ， 如 图 16-55 所 示 。 


20 to 40 of 100 available for paging 


图 16-55” 翻 页 


paging 其 实 是 一 次 请 求 下 来 设 定 大 小 的 全 部 数据 ， 然 后 在 浏览 器 上 分 页 显示 ， 而 不 是 调用 scroll API 来 逐步 显示 。 所 以 ， 千 万 不 要 设置 太 大 ! 
2. 仪 表盘 纲要 属性 
table 面 板 在 仪表 盘 纲要 中 对 应 的 可 设置 属性 如 表 16-2 所 示 。 


表 16-2 table 面 板 的 可 设置 属性 


属 性 说 有 明 


size 每 页 显示 多 少 条 
pages 展示 多 少 页 
( 续 ) 
属 性 说 了 明 
offset 当前 页 的 页 码 
sort 定义 表格 排序 次 序 的 数组 ， 示 例如 右 : [ '(GQtmestamp' . 'desc' ] 
overflow css 的 overflow 属性 。 ‘min-height’ (expand) 或 “auto (scroll) 
fields 表格 显示 的 字段 数组 
highlight 高 亮 显 示 的 字段 数组 
sortable 设 为 假 表示 关 掉 排 序 功 能 
header 设 为 假 表 示 隐 藏 表格 列 名 
paging 设 为 假 表 示 隐 藏 表格 翻 页 键 


field list 设 为 假 表 示 隐 藏 字段 列表 。 使 用 者 依然 可 以 展开 它 ， 不 过 默认 会 隐藏 起 来 
all_fields 设 为 真 表示 显示 映射 表 内 的 所 有 字段 ， 而 不 是 表格 当前 使 用 到 的 字段 
裁 前 因子 (trim factor)， 是 参考 表格 中 的 列 数 来 决定 裁剪 字段 长 度 。 比 如 说 ， 设 置 裁剪 因子 为 
trimFactor |100, 表格 中 有 5 列 ， 那 么 每 列 数据 就 会 被 裁剪 为 20 个 字符 。 完 整 的 数据 依然 可 以 在 展开 这 个 事件 
后 查看 到 


localTime 设 为 真 表示 调整 tmeField 的 数据 遵循 浏览 器 的 本 地 时 区 
timeField 如 果 localTime 设 为 真 ， 该 字段 将 会 被 调整 为 浏览 器 本 地 时 区 
spyable 设 为 假 表 示 不 显示 审查 (inspect) 按钮 


16.4.3 map 


map 面 板 把 两 个 字母 的 国家 或 地 区 代码 转 成 地 图 上 的 阴影 区 域 。 目 前 可 用 的 地 图 包括 世界 地 图 、 美 国 地 图 和 欧洲 地 图 。 


1. 界 面 配置 说 明 


考虑 到 都 是 中 国 读者 ， 本 节 会 多 加 部 分 中 国 地 图 讲解 。 注 意 中 国 地 图 代码 ， 基 于 本 人 https://github.com/chenryn/kibana.git 仓 库 ， 除 标准 的 map 面 板 参 数 外 ， 还 提供 了 terms_stats 功 能 ， 也 会 一 并 


map 面 板 ， 最 重要 的 配置 即 输入 字段 ， 对 于 不 同 的 地 图 ， 应 该 配置 不 同 的 Field: 


:world: 对 于 世界 地 图 ， 其 所 支持 的 格式 为 由 2 个 字母 构成 的 国家 名 称 缩 写 ， 比 如 : US，CN，JP 等 。 如 果 你 使 用 了 LogStash: : Filters: : GeoIP 插 件 ， 那 么 默认 生成 的 geoip.country_code2 字 段 正好 符合 


ten: 对 于 中 国 地 图 ， 其 所 支持 的 格式 则 是 由 2 个 数字 构成 的 省 份 编码 ， 比 如 : 01 ( 即 安徽 ) , 30 ( 即 广东 ) , 04 ( 即 江 苏 ) 等 。 如 果 你 使 用 了 LogStash: : Filters: : GeoIP 插 件 ， 那 么 默认 生成 的 


呈 oip.region_name 字 段 正好 符合 条 件 。 


如 果 你 使 用 了 我 的 仓库 代码 ， 或 者 自行 合并 这 个 patch: https://github.com/elasticsearch/kibana/pull/1270， 你 的 map 面 板 配 置 界面 会 稍 有 变动 成 图 16-56 的 样子 。 


Select Panel Type 


n 


map * Note: This row is full, new pansis will wrap to a new line. You shouki add another row. 


Stable // Displays a map of shaded regions using a field containing a 2 letter country , or US state, code. Regions with more hit are : 
important that you set it to the corract field. 
Titie Span Editabee inspect 9 


© a 


Map 
terms 


terms stats : H woria 


图 16-56 ”terms_stats 地 图 配置 


如 果 选择 terms_stats 模 式 ， 就 会 和 histogram 面 板 一 样 出 现 需要 填写 value_field 的 位 置 。 同 样 必须 使 用 在 Elasticsearch 中 是 数值 类 型 的 字段 ， 然 后 显示 的 地 图 上 ， 就 不 再 是 个 数 而 是 具体 的 均值 ， 最 大 
值 等 数据 了 。 


map 面 板 在 仪表 盘 纲 要 中 对 应 的 可 设置 属性 包括 : 


- map: 显示 哪个 地 图 : world, usa europes 

: colors: 用 来 涂抹 地 图 阴影 的 颜色 数组 。 一 旦 设 定好 这 两 个 颜色 ， 阴 影 就 会 使 用 介 于 这 两 者 之 间 的 颜色 。 示 例 [“#AOE2E2” ， “#265656”]。 
size: 阴影 区 域 的 最 大 数量 。 

:exclude: 排除 的 区 域 数组 。 示 例 [ “US”， BR, IN? ]. 


"spyable: 设 为 假 ， 不 显示 审查 (inspect) 按钮 。 


bettermap 面 板 之 所 以 叫 这 个 名 字 是 因为 还 没有 更 好 的 名 字 。bettermap 使 用 地 理 坐 标 来 在 地 图 上 创建 标记 集群 ， 然 后 根据 集群 的 密度 ， 用 橘 色 、 黄 色 和 绿色 作为 区 分 。 


要 查看 细节 ， 点 击 标记 集群 。 地 图 会 放大 ， 原 有 集群 分 裂 成 更 小 的 集群 。 一 直 小 到 没 法 成 为 集群 的 时 候 ， 单 个 标记 就 会 显现 出 来 。 悬 停 在 标记 上 可 以 查看 tooltip 设 置 的 值 。 


Oza 


bettermap 在 第 一 次 访问 时 需要 从 互联 网 上 下 载 它 的 地 图 文件 。 


界面 配置 说 明 


bettermap 面 板 是 为 了 解决 map 面 板 地 图 种 类 太 少 和 且 不 方便 大 批量 添加 各 国 地 
在 使 用 的 时 候 单独 请 求 下 载 ， 所 以 在 初次 使 用 的 时 候 会 需要 一 点 时 间 才 能 正确 显示 。 


IR] 


H 


D 


文件 的 问题 开发 的 。 它 采用 了 leaflet 库 (http://leafletjs.com/) ， 其 LitileLayer 加 载 的 OpenStreetMap 地 


[R] 


文件 都 是 


在 bettermap 的 配置 界面 ， 只 有 一 个 必 填 的 字段 名 。 如 果 使 用 的 是 logstash-filter-geoip 的 话 ， 这 里 应 该 填写 的 是 geoip.location 字 段 。 额 外 的 ， 我 提供 了 一 个 provider 选 择 菜 单 ， 可 以 选择 各 种 地 医 
供 商 。 比 如 中 文 用 户 可 以 选择 GaoDe (高 德 地 图 ) ， 效 果 如 图 16-57 所 示 。 


T3 
D] 


Leatiet | A185 FR 


图 16-57 ”高 德 地 


Qus 


最 近 ， 高 德 地 图 的 API 出 现 问题 ， 该 provider 已 经 无 法 使 用 。 


2. 仪 表盘 纲要 属性 


bettermap 面 板 在 仪表 盘 纲要 中 对 应 的 可 设置 属性 包括 : 


: feld: 包含 了 地 理 坐 标的 字段 ， 要 求 是 geojson 格 式 。GeoJSON 是 一 个 数组 ， 内 容 为 [longitude ，latitude]。 这 可 能 跟 大 多 数 实现 ([latitude，longitude]) 是 反 过 来 的 。 请 注意 不 是 任意 数组 都 行 ， 而 是 必须 
在 Elasticsearch 中 映射 成 了 geo_point 类 型 的 特殊 字段 才 行 。 映 射 设置 方式 见 本 书 第 12 章 。 


“size: 用 来 绘制 地 图 的 数据 集 大 小 。 默 认 是 1000。 
Oze 
bettermap 只 展示 固定 条 数 的 数据 ， 跟 map 采 用 termFacet 请 求 相 比 ， 其 实质 是 不 一 样 的 。 二 者 并 不 是 互 措 关 系 。 此 外 ，table 面 板 默认 是 展示 最 近 500 条 ， 跟 这 里 的 默认 大 小 不 一 致 ， 也 有 可 能 引起 误解 。 
' spyable: 设 为 假 ， 不 显示 审查 (inspect) 按钮 。 
“ tooltip: 是 停 在 标记 上 时 显示 哪个 字段 。 


“ provider: 选择 哪 家 地 图 提供 商 。 


leaflet 库 有 丰富 的 插件 资源 (http://leafletjs.com/plugins.html) ， 比 如 热力 图 (http://www.patrick-wied.at/static/heatmapjs/example-heatmap-leaflet.html) 。 效 果 如 图 16-58。 
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图 16-58 ”热力 图 


Os 


热力 图 插件 最 终 在 Kibana 4.1 中 ， 作 为 tile map 的 新 option 加 入 了 。 


其 实 Kibana 官 方 效果 的 标记 集群 也 是 插件 实现 的 ， 叫 markercluster (https://github.com/Leaflet/Leaflet.markercluster) 。 


16.4.5 terms 


这 种 面板 基于 Elasticsearch 的 terms facet 接 口 数据 展现 表格 、 柱 状 图 或 者 饼 图 。 


1. 界 面 配置 说 明 


terms 面 板 是 针对 单项 数据 做 聚合 统计 的 面板 ， 可 配置 项 比较 简单 ， 如 图 16-59 示 。 


主要 分 为 两 部 分 ， 数 据 模式 和 显示 风格 。 下 面 分 别 介绍 。 


Field Length Exclude Terms(s) (comma separated) 


h5 view. platfc 10 


Legend Format ^ Missing Other Donut Tilt 


horizonte $) UN v d e Vv 


图 16-59 terms panel 配 置 页 


“ 数据 模式 : terms 面 板 能 够 使 用 两 种 数据 模式 (也 是 Kibana 大 多 数 面板 所 使 用 的 ) : 


分 类 计数 (类 比 为 group by 语法 ) 。 填 写 有 具体 字段 名 即 可 。 此 外 ， 排 序 (order by) 和 结果 数 (limit) 也 可 以 定义 ， 具 体 选 项 介绍 见 本 页 前 半 部 分 。 


' terms: 即 普通 的 分 
- terms stats: 在 terms 的 基础 上 获取 另 一 个 数值 类 型 字段 的 统计 值 作 为 显示 内 容 。 可 选 的 统计 值 有 : count、total_count、min、max、total、mean， 最 常用 的 就 是 mean。 
“ 显示 风格 : terms 面 板 可 以 使 用 多 个 风格 来 显示 数据 。 


: Bar (柱状 图 ) 示例 如 图 16-60 所 示 。 


平台 版 本 占 比 O 6 ^ x 


6 Android4.2.2 (2975239) € Android4.1.2 (2736637) € Android4.3 (2048632) ® iPhone712 (1840038) 
Android4.4.2 (1665287) ® Android4.0.4 (1425584) ® Android4.1.1 (1357099) ^ other (1317625) 
Android4.2.1 (1295143) 6 iPhone711 (598772) Other values (4273593) 

5000000 


图 16-60 bar 


-Pie 〈 饼 图 ) 示例 如 图 16-61。 


浏览 器 版 本 占 比 6 ù + x 


€ UC 939.2.467 (2736033) € WEIBO unknown (1668710) € iPhone 7.0(1404166) € Android 4.2.2 (1254707) 
Android 4.1.2 (1204162) UC. 9.9.3.478 (1068568) UC 9.8.5.471 (1037974) Android 4.3 (747814) 
UC 9.9.0.459 (693928) ® Android 4.0.4 (624738) Other values (9092888) 


图 16-61 ”pie 图 


这 时 候 可 能 就 会 觉得 这 个 “other value” 太 大 了 ， 又 不 关心 它 。 那 么 可 以 在 配置 里 去 掉 other 的 勾 选 ， 图 形 会 变 成 图 16-62 这 样 。 


浏览 器 版 本 占 比 O 0 + x 


€ UC 93.9.2.467 (2730318) © WEIBO unknown (1669485) «€ IPhone_7.0 (1404234) ® Android 4.2.2 (1254845) 
Android 4.1.2(1204289) ® UC 9.9.3.478 (1068806) ® UC 9.8.5471 (1037980) ^ Android 4.3 (747849) 
UC. 9.9.0.459 (693975) € Android 4.0.4 (624812) 


图 16-62 ”无 missing 的 pie 图 
WROD “donut” ， 则 可 以 看 到 甜 甜 圈 饼 图 的 效果 ， 如 图 16-63 所 示 。 


浏览 器 版 本 占 比 O 0 中 x 
6 UC 93.2.467 (2736319) € WEIBO unknown (1663485) € iPhone 7.0(1404234) € Android 4.2.2 (1254845) 


Android 4.1.2 (1204289) UC. 9.9.3.478 (1068806) UC. 9.8.5.471 (1037980) Android 4.3 (747849) 
UC, 9.9.0.459 (693975) © Android 4.0.4 (624812) 


图 16-63” 甜 甜 圈 饼 图 


“ table: 如 果 你 是 个 对 数字 敏感 的 人 ， 或 者 主要 数据 差距 不 大 ， 通 过 柱状 图 或 者 饼 图 方式 不 是 很 明显 ， 那 么 看 表格 最 好 了 。 如 图 16-64 所 示 。 


平台 版 本 占 比 


Term Count 

Android4.2.2 2975523 
Android4.1.2 2736628 
Android4.3 2048991 
iPhone712 1840385 
Android4.4.2 1665541 
Android4.0.4 1425813 
Android4.1.1 1357238 
other 1317517 
Android4.2.1 1294927 


iPhone711 598542 


Missing field 0 


Other values 4274653 


图 16-64 ”表格 显示 


注意 ， 这 个 表格 只 有 单列 数据 ， 使 用 配置 里 定义 的 排序 ， 不 像 table 面 板 。 如 果 你 需要 同时 看 多 种 统计 数据 ， 则 应 该 使 用 stats 面 板 。 


:scfipt field: 为 了 达到 更 灵活 的 效果 ， 我 的 版 本 在 这 里 多 提供 了 一 个 功能 。 在 fmode 选 择 sctript 的 时 候 ， 可 以 填写 sctipt 脚 本 字符 串 获 取 脚 本 化 字段 结果 做 聚合 。 


在 scriptField 输 入 框 中 输入 : 


doc['path.raw'].value 


的 时 候 ， 效 果 完全 等 价 于 直接 在 Field 输 入 框 中 输入 : 


path.raw 


因为 script 和 analyzer 的 次 序 关系 ， 务 必 使 用 带 有 “not_analyzed” 属性 的 字段 。 否 则 一 条 数据 会 返回 多 个 分 词 结果 各 自 参与 后 续 的 script 运 算 。 


支持 的 script 语 法 ， 请 参阅 Elasticsearch 官 方 文档 : http://www.elasticsearch.org/guide/en/elasticsearch/reference/3.0/modules-scripting.html document field 


出 于 安全 考虑 ，Elasticseatch 推 荐 大 家 关闭 动态 提交 脚本 的 功能 。 所 以 ， 请 在 确保 自己 集群 安全 性 的 前 提 下 使 用 该 功能 。 


terms 面 板 在 仪表 盘 纲要 中 对 应 的 可 设置 属性 参见 表 16-3。 


表 16-3 tetms 面 板 的 可 设置 属性 


属 性 说 。 有明 


field 用 于 计算 facet 的 字段 名 称 

script 用 于 提交 facet 的 scriptField 脚本 字符 串 。 系 我 的 fork 中 新 增 的 功能 ， 仅 在 fmode 为 script 时 生效 
exclude 要 从 结果 数据 中 排除 掉 的 terms 

missing 设 为 假 ， 就 可 以 不 显示 数据 集 内 有 多 少 结果 没有 你 指定 的 字段 

other 设 为 假 ， 就 可 以 不 显示 聚合 结果 在 你 的 size 属性 设 定 范围 以 外 的 总 计数 值 

size 显示 多 少 个 terms 


terms 模式 可 以 设置 : count, term, reverse count 或 者 reverse term ; terms stats 模式 可 以 设置 : 
order term, reverse term, count, reverse count, total, reverse total, min, reverse min, max, reverse max, 


mean 或 者 reverse mean 


donut 在 饼 图 (pie) 模式 ， 在 饼 中 男 个 图 ， 变 成 甜 甜 圈 样 式 
tilt EHE (pie) 模式 ， 倾 斜 饼 变 成 椭圆 形 
lables 在 饼 图 (pie) 模式 ， 在 饼 图 分 片上 绘制 标签 
amangemen | ”在 柱状 图 Cbar) 或 者 饼 图 (pie) 模式 ， 图 例 的 摆 放 方向 。 可 以 设置 : 水 平 (horizontal) 或 者 垂直 
a ( vertical ) 
chart 可 以 设置 : table, bar 或 者 pie 
counter pos 图 例 相 对 于 图 的 位 置 ， 可 以 设置 上 (above), F (below )， 或 者 不 显示 (none). 
( 续 ) 
属 性 说 —H 
spyable 设 为 假 ， 不 显示 审查 (inspect) 按钮 


tmode Facet 模式 : terms 或 者 terms. stats 
Field 模式 : normal 或 者 script。 我 的 fork 中 新 增 和 参数，normal 行为 和 原版 一 致 ， 选 择 script 时 ， 


fmode 

scriptField 参数 生效 
tstat terms stats 模式 下 的 facet stats 字段 
valuefield terms stats 模式 下 的 facet value 字段 


16.4.6 column 


这 是 一 个 伪 面 板 ， 目 的 是 让 你 在 一 列 中 添加 多 个 其 他 面板 。column 面 板 的 限制 还 是 很 多 的 ， 比 如 不 能 拖 搜 内 部 的 小 面板 。 


1. 界 面 配置 说 明 


column 面 板 是 为 了 在 高 度 较 大 的 row 中 放 入 多 个 小 panel 准 备 的 一 个 容器 。 其 本 身 配置 界面 和 row 类 似 ， 只 有 一 个 panel 列 表 。 如 图 16-65 所 示 。 


Column Settings 


图 16-65 column panel 配 置 


在 column 里 的 具体 子 属性 设 定 ， 需 要 点 击 子 面板 自 带 的 配置 按钮 来 配置 ， 而 不 是 column 的 按钮 。 如 图 16-66 所 示 。 


2. 仪 表盘 纲要 属性 


column 面 板 在 仪表 盘 纲 要 中 对 应 的 可 设置 属性 只 有 一 个 ， 就 是 : panel。 由 内 部 的 面板 对 象 构成 的 数组 。 


16.4.7 stats 


这 种 面板 基于 Elasticsearch 的 statistical Facet 接 口 实现 的 统计 聚合 进行 数据 展示 ， 参 数 设 置 参见 表 16-4。 


表 16-4 stats 面 板 的 可 设置 属性 


属 性 i 明 
format 返回 值 的 格式 。 默 认 是 number， 可 选 值 还 有 : money, bytes, float 
style 主 数字 的 显示 大 小 ， 默 认为 24pt 


用 来 做 主 数字 显示 的 聚合 值 ， 默 认 是 count， 可 选 值 为 : count (计数 ) min. (最 小 值 )、max ( 最 大 值 )、 
mean (平均 值 )、total (总 数 )、variance (方差 )、std_deviation (标准 差 )、sum_of squares (平方 和 ) 


show 统计 表格 中 具体 展示 的 哪些 列 。 默 认为 全 部 展示 ， 可 选 列 名 即 mode 中 的 可 选 值 
spyable 设 为 假 ， 不 显示 审查 (inspect) 按钮 


mode 


16.4.8 query 


query 面 板 和 filter 面 板 都 是 特殊 类 型 的 面板 ， 在 仪表 盘 上 有 且 仅 能 有 一 个 ， 不 能 删除 不 能 添加 。 


query 和 filter 面 板 的 普通 样式 和 基本 操作 ， 在 之 前 16.3.1 节 “请 求 和 过 滤 ” 中 已 经 讲述 过 。 这 里 额外 讲 一 些 高 阶 功能 。 


1. 请 求 类 型 
query 搜 索 框 支持 三 种 请 求 类 型 : 
- lucene: 这 也 是 默认 的 类 型 ， 使 用 要 点 就 是 请 求 语法 。 语 法 说 明 在 之 前 Elasticseatch 一 章 已 经 讲 过 。 


- regex: 使 用 Elasticsearch 的 regex guery 语 法 。 参 见 第 9 章 。 


“ topN: topN 是 一 个 方便 大 家 进行 多 项 对 比 搜索 的 功能 ， 其 配置 界面 如 图 16-67 所 示 。 
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116-66 ”column 里 的 子 面板 设置 按钮 
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其 运行 实质 ， 是 先 根据 你 填写 的 field 和 size， 发 起 一 次 termsFacet 查 询 ， 获 取 topN 的 term 结 果 ; 然后 拿 着 这 个 列表 ， 逐 一 发 起 附加 了 term 条 件 的 其 他 请 求 ( 比 如 绑 定 在 histogram 面 板 就 是 
date_histogram 请 求 ，stats 面 板 就 是 termStats 请 求 ) ， 也 就 获得 了 topN 结 果 。 图 16-68 就 是 一 次 topN query 对 应 的 histogram 面 板 。 
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图 16-68  topN histogram 
如 果 Elasticsearch 响 应 较 慢 的 时 候 ， 你 甚至 可 以 很 明显 地 看 到 histogram 面 板 上 的 多 条 曲线 是 一 条 一 条 出 来 数据 绘制 的 。 
2. 别 名 


query 还 可 以 设置 别名 (alias) 。 默 认 没有 别名 的 时 候 ， 各 panel 上 显示 对 应 query 时 ， 会 使 用 具体 的 query 语 句 。 在 查询 比较 复杂 的 时 候 ， 不 便 观 看 。 而 设置 别名 后 ，pinned queries, panels 
处 ， 都 会 只 显示 设置 好 的 别名 ， 而 不 再 显示 复杂 的 查询 语句 ， 这 样 一 目 了 然 。 别 名 效果 在 之 前 图 16-13 中 其 实 已 经 有 演示 。 


16.4.9 trend 


trend 面 板 以 证 券 报 价 器 风格 展示 请 求 随 着 时 间 移 动 的 情况 。 比 如 当前 时 间 是 1: 10pm， 你 的 时 间 选 择 器 设置 的 是 Last 10m 


， 而 本 面板 的 Time Ago 参 数 设置 的 是 1h， 那 么 面板 会 显示 的 是 请 求 结果 从 
12: 00-12: 10pm 以 来 变化 了 多 少 。 


1. 界 面 配 置 说 明 


trend 面 板 用 来 对 比 实时 数据 与 过 去 某 天 同期 数据 量 的 变化 。 配 置 很 简单 ， 就 是 设置 具体 某 天 前 ， 如 图 16-69 所 示 。 


List Format Reverse Colors © 


vertical E 


图 16-69 trends X H 


配合 topN query 效 果 更 佳 ， 如 图 16-70 所 示 。 


TOPS5 请 求 量 今 昨 日 涨幅 


(pages detailJson (H5 首 页 )) 


(pages. index (H5 首 页 )) 
(index. feed (H5 首 页 )) 
(index action (H5 首 页 


(pages. detailTpl v5 (H5 首 页 ) 


图 16-70 topN+trends 


trend 面 板 在 仪表 盘 纲要 中 对 应 的 可 设置 属性 包括 : 


“ ago: 描述 需要 对 比 请 求 的 时 期 的 时 间 数 值 型 字符 串 。 
- arrangement: horizontal X verticalo 


- spyable: 设 为 假 ， 不 显示 审查 (inspect) 按钮 。 


text (文本 ) 面板 用 来 显示 静态 文本 内 容 ， 支 持 markdown、 简 单 的 html 和 纯 文本 格式 。 一 般 用 来 写 一 些 说 明文 字 、 辅 助 链接 等 等 。 


text 面 板 在 仪表 盘 纲要 中 对 应 的 可 设置 属性 包括 : 


- mode: html, markdown Ñ # texto 


“ content: 面板 内 容 ， 用 mode 参 数 指定 的 标记 语言 书写 。 


sparklines 面 板 显示 微型 时 间 图 ， 目 的 不 是 显示 一 个 确切 的 数值 ， 而 是 以 紧凑 的 方式 显示 时 间 序 列 的 形态 。 常 用 于 监控 场景 中 ， 比 如 官方 的 Marvel。 


sparklines 面 板 其 实 就 是 histogram 面 板 的 缩 略 图 模式 。 在 配置 上 ， 只 能 选择 Chart value 模 式 ， 填 写 Time Field 或 者 Value Field 字 段 。 前 面 几 节 描述 的 interval 在 配置 页 面 上 是 看 不 到 的 。 实 际 配 
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图 16-71 所 示 。 
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图 16-71 sparklines 配 置 页 面 


D 


我 们 可 以 对 比 一 下 


16-72 中 对 同一 个 topN 请 求 绘制 的 sparklines 和 之 前 图 16-68 中 histogram 面 板 的 效果 。 
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图 16-72  sparklines E] 


2. 仪 表盘 纲要 属性 


sparklines 面 板 在 仪表 盘 纲 要 中 对 应 的 可 设置 属性 包括 : 


- mode: 用 作 Y 轴 的 数值 模式 。 除 count 以 外 ， 都 需要 定义 value_field 字 段 。 可 选 值 有 : count. mean, max. min. total, 
: üme field: X 轴 字段 。 必 须 是 Elasticseatch 中 的 时 间 类 型 字段 。 

- value, field: 如 果 mode 设 置 为 mean、max、min 或 者 totdl，Y 轴 字段 。 必 须 是 数值 类 型 字段 。 

- interval: 如 果 有 现成 的 时 间 过 滤器 ，Sparkline 会 自动 计算 间隔 ; 如 果 没 有 ， 就 用 这 个 间隔 。 黑 认 是 5 分 钟 。 


*spyable: 显示 inspect 图 标 。 


16.4.12 hits 


hits 面 板 显示 仪表 盘 上 每 个 请 求 的 hits 数 ， 具 体 的 显示 格式 可 以 通过 chart 属 性 配置 指定 。 


hit 参 数 参见 前 面 16.4.5 节 表 16-3。 


16.4.13 goal 


goal 面 板 在 一 个 饼 图 上 显示 到 达 指 定 目标 的 进度 。 将 请 求 得 到 的 hits 总 数 ， 除 以 输入 的 Goal 目 标 数 ， 得 到 的 百分比 。 参 数 设置 参见 前 


- query.goal: 设 定 的 目标 数 ， 默 认 是 100。 注 意 这 里 是 quety.goal， 不 是 各 面板 通用 的 绑 定 请 求 用 的 queties.* 属 性 。 


legend: 图 例 的 位 置 ， 上 、 下 或 者 无 。 


16.5 ”仪表 盘 的 保存 和 载 入 


面 16.4.5 节 表 16-3， 有 两 个 不 一 样 的 参数 如 下 


通过 上 一 节 详细 的 面板 介绍 ， 是 不 是 觉得 入 门 章节 的 simple dashboard 确 实 是 好 简单 ”假如 你 已 经 给 自己 的 日 志 数据 构建 了 一 个 像 


新 后 挂 在 一 个 大 屏幕 上 。 怎 么 保证 自己 的 辛苦 劳动 不 会 丢失 呢 ? 


Kibana 可 以 把 仪表 盘 设计 持久 化 到 Elasticsearch 里 ， 然 后 在 需要 的 时 候 通过 加 载 菜单 或 者 URL 地 址 调 出 来 。 


16-73 这 样 漂亮 的 仪表 盘 ， 现 在 打算 分 享 给 团 


队 ， 或 者 开启 


自动 刷 


sA Logstash Search 


图 16-73 ”仪表 盘 示 例 


16.5.1 保存 仪表 盘 


保存 界面 非常 简单 ， 如 图 16-74 所 示 ， 打 开 保存 下 拉 菜 单 ， 取 个 名 字 ， 然 后 点 击 保存 图 表 即 可 。 


to a minute ago = A = 
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图 16-74 把 仪表 盘 保 存 到 Elasticsearch 
16.5.2 “加载 仪表 盘 


要 搜索 已 保存 的 仪表 盘 列表 ， 点 击 右 上 角 的 加 载 图 标 。 在 这 里 你 可 以 加 载 、 分 享 和 删除 仪表 盘 ， 如 图 16-75 所 示 。 


„al Laura's Dashboard 
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图 16-75 ”dashboard 列 表 


16.5.3 ”分 享 仪表 盘 


已 保存 的 仪表 盘 可 以 通过 你 浏览 器 地 址 栏 里 的 URL 分 享 出 去 。 每 个 持久 化 到 Elasticsearch 里 的 仪表 盘 都 有 一 个 对 应 的 URL， 像 下 面 这 样 : 


http://your_host/index.html#/dashboard/elasticsearch/MYDASHBOARD 


这 个 示例 中 MYDASHBOARD 就 是 你 在 保存 的 时 候 给 仪表 盘 取 的 名 字 。 


你 还 可 以 分 享 一 个 即时 的 仪表 盘 链 接 ， 如 图 16-76 示 ， 点 击 Kibana 右 上 角 的 分 享 图 标 ， 会 跳出 图 16-77 所 示 浮 层 ， 内 带 一 个 临时 URL。 默 认 情 况 下 ， 临 时 URL 保 存 30 天 。 你 可 以 把 这 个 URL 发 给 其 他 人 直 
接 访问 。 
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图 16-76 ”分 享 按钮 
Laura's Dashboard ........ 


Share this dashboard with this URL 


图 16-77 临时 URL 


仪表 盘 可 以 保存 到 你 的 服务 器 磁盘 上 成 为 json 文 件 。 把 文件 放 到 app/dashboards 目 录 ， 然 后 通过 下 面 地 址 访问 。 


http://your host/index.html#/dashboard/file/MYDASHBOARD.json 


MYDASHBOARD.json 就 是 磁盘 上 文件 的 名 字 。 注 意 路 径 中 的 /#dashboard/file/ 看 起 来 跟 之 前 访问 保存 在 Elasticsearch 里 的 仪表 盘 很 类 似 ， 不 过 这 里 访问 的 是 文件 而 不 是 Elasticsearch。 导 出 的 仪表 盘 
纲要 的 详细 信息 ， 请 阅读 16.6.1 节 “scheme” 简 介 。 


Kibana 仪 表盘 可 以 很 容易 地 在 浏览 器 中 创建 出 来 ， 而 且 绝 大 多 数 情况 下 ， 浏 览 器 已 经 足够 支持 你 创建 一 个 很 有 用 很 丰富 的 节目 了 。 不 过 ， 当 你 真 的 需要 一 点 小 修改 的 时 候 ，Kibana 也 可 以 让 你 直接 编辑 
仪表 盘 的 纲要 。 
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我 们 使 用 图 16-78 中 的 仪表 盘 作 为 示例 。 按 图 中 指示 操作 ， 点 击 右 上 角 的 保存 按钮 ， 指 向 高 级 (Advanced) 菜单 ， 然 后 点 击 导 出 纲要 (Export Schema) 。 示 例 使 用 的 纲要 文件 也 可 以 直接 通过 右边 链 
BERE 


„añ Romeo and Juliet 


Save as Home 
Reset Home 


PERCENTAGE OF TOTAL 


图 16-78 ”导出 纲要 按钮 


因为 仪表 盘 是 由 特别 长 的 JSON 文 档 组 成 的 ， 我 们 只 能 分 成 一 段 段 的 内 容 ， 分 别 介绍 每 段 的 作 


和 目的 。 


和 所 有 的 JSON 文 档 一 样 ， 都 是 以 一 个 大 括号 { 开 始 的 。 


1. 服 务 (services) 


“services”: ( 


服务 (Services) 是 被 多 个 面板 使 用 的 持久 化 对 象 。 目 前 仪表 盘 对 象 附加 有 两 种 服务 对 象 ， 不 指明 的 话 ， 就 会 自动 填充 成 请 求 (query) 和 过 滤 (filter) 服务 了 。 


query 服 务 如 下 所 示 : 
query” : ( 
"list { 
“O 
2 "play name: V' Romeo and JulietN "" , 
"KTEB2GD" , 


请 求 服务 主要 是 由 仪表 盘 项 部 的 请 求 栏 控 制 的 。 有 两 个 属性 : 


List: 一 个 以 数字 为 键 的 对 象 。 每 个 值 描述 一 个 请 求 对 象 。 请 求 对 象 的 键 命名 一 目 了 然 ， 就 是 描述 请 求 输入 框 的 外 观 和 行为 的 。 


- Ids: 一 个 由 ID 组 成 的 数组 。 每 个 ID 都 对 应 前 面 list 对 象 的 键 。ids 数 组 用 来 保证 显示 时 list 的 排序 问题 。 


filter 服 务 如 下 所 示 : 


"filter" : ( 
"list" : ( 
"0f us d 
"type" : "querystring' , 
“query” : "speaker: ROMEO” , 
"mandate" : "must" , 
"active" : true, 
"alas" : 075, 
"id" : 0 
H 
ii ， 
"ids" : [ 
0 


过 滤 的 行为 和 请 求 很 像 ， 不 过 过 滤 不 能 在 面板 级 别 选 择 ， 而 是 对 全 仪表 盘 生效 。 过 滤 对 象 和 请 求 对 象 一 样 有 list 和 ids 两 个 属性 ， 各 属性 的 行为 和 请 求 对 象 也 一 样 。 


2. 垂 幕 (pulldown) 


“pulldowns” : [ 


垂 幕 是 一 种 特殊 的 面板 。 或 者 说 ， 是 一 个 特殊 的 可 以 


来 放 面 板 的 地 方 。 在 垂 幕 里 的 面板 就 跟 在 行 里 的 一 样 ， 


可 以 被 使 


者 移动 或 编辑 。 所 以 垂 幕 特别 适合 放置 输入 框 。 垂 幕 的 属性 是 一 个 由 面板 对 象 构成 的 数组 : 


{ 


“type” : “query” , 
“collapse” : false, 
“notice” : false, 


H 


板 永 远 都 是 全 


区 别 就 是 不 能 设置 span 宽 度 。 垂 幕 里 的 


FER. itih EERI 


板 也 不 


"enable" : true, 
"query! : 79", 
“pinned” : true, 
"history' : [ 


"play name: V' Romeo and JulietV 7 
“Playname: \” Romeo and Juliet\“”， 


"romeo" 
l; » 
remember" : 

" 

i ua » 
type : 
“collapse” : 
"notice" : 

"enable" : 
i 

l; 


10 


“filtering” , 


false, 


true, 
true 


H 


E 幕 面板 有 两 个 普通 行 面板 没有 的 选项 : 


“Collapse: 设置 为 真 假 值 ， 代 表 着 面板 被 折 胎 还 是 展开 。 


Notice: 面板 设置 这 个 值 ， 控 制 在 垂 幕 的 标签 主题 上 出 现 一 个 小 星星 。 用 来 通知 使 用 者 ， 这 个 面板 里 发 生变 动 了 。 


3. 导 航 (nav) 


nav 属 性 里 也 有 一 个 面板 列表 ， 只 是 这 些 面板 是 


来 填充 在 页 首 导航 栏 里 的 。 目 前 唯一 支持 导航 的 面板 是 时 间 选 择 器 (timepicker) ， 如 下 所 示 : 


"nav : [ 
type” : 
notice" : 


enable" : 
status” : 


collapse" : 
false, 
true, 


"timepicker" , 


false, 


"Stable" , 


time options" : [ 
"sm"; 


l; 


"refresh intervals" : [ 


l; 

“timefield” : “@timestamp” 
} 

]， 


4.loader 


loader 属 性 描述 了 仪表 盘 顶 部 的 保存 和 加 载 按钮 的 行为 ， 如 下 所 示 : 


“loader” : { 
"save gist' : false, 
"save elasticsearch" : 
"save local' : true, 
"save default" : true, 
"save temp" : true, 
"save temp ttl enable" : 
"save temp ttl" : "30d" , 
"load gist” : false, 
"load elasticsearch' : true, 
"load elasticsearch size" : 
"load local' : false, 
"hide" : false 


true, 


20, 


b 


5. 行 数组 


rows 就 是 通常 放置 面板 的 地 方 。 也 是 唯一 可 以 通过 浏览 器 页 面 添加 的 位 置 : 


"rows" : [ 

Ua » « » 
title" : Charts” , 
“height” : “150px” , 
"editable" : true, 
“collapse” : false, 
"collapsable" : true, 


行 对 象 包含 了 一 个 面板 列表 ， 以 及 一 些 行 的 具体 参数 ， 如 下 所 示 : 


- title: 行 的 标题 。 
“ height: 行 的 高 度 ， 单 位 是 像素 ， 记 作 Px。 
“ editable: 真 假 值 代表 面板 是 否 可 被 编辑 。 


“ collapse: HARER RITE Tii o 


- collapsable: 真 价值 代表 使 用 者 是 否 可 以 折合 行 。 


6. 面 板 数 组 


行 的 panels 数 组 属性 包括 有 一 个 以 自己 出 现 次 序 排序 的 


回 


板 对 象 的 列表 。 各 特定 


回 


板 本 身 的 


属性 列表 和 说 明 ， 在 之 前 各 


板 介绍 小 节 中 都 介绍 过 了 。 下 


回 


是 


个 示例 : 


"panels" : [ 


"span" : 8, 

editable" : true, 

"type" : "terms" , 
^loadingEditor' : false, 
"field' : "speech number" , 
"exclude" : [], 

"missing' : false, 
"other" : false, 

"size" : 10, 

“order” : “count” , 
"style" : ( 

"font-size" : "10pt" 
] 7 

“donut”: false, 

“tilt” : false, 
“labels” : true, 
“arrangement” : “horizontal” , 
"chart" : "bar" , 
"counter pos” : “above” , 
"spyable" : true, 
"queries" : ( 

"mode" : “all”, 

"las : [ 

0 

] 
), 
"tmode" : “terms” , 
"tstat' : “total” , 
"valuefield" : "", 
"title" "Longest Speeches 

) 
{ 

“error” : false, 
“span” : 4, 
“editable true, 
"type" : “goal” , 
"loadingEditor' : false, 
“donut” : true, 
"tilt" : false, 
legend? none” , 


"spyable" : true, 
query .: { 
“goal” : 111397 
H 


“queries” : { 
"mode" : “all”, 
"ids" : [ 
0 
] 
" 
“title” : "Percentage of Total" 
$ 
] 
} 
l 
7. 索 引 设置 


索引 属性 包括 了 Kibana 交 互 的 Elasticsearch 索 引 的 信息 。 


"index" : ( 
"interval' : "none" , 
“default” : “all”, 
“pattern” : ^"[logstash-]YYYY.MM.DD' , 
"warm fields" : false 


b 


- interval: none，houf，day，week，month。 这 个 属性 描述 了 索引 所 遵循 的 时 间 间 隔 模式 。 

“ default: 如 果 interval 被 设置 为 none， 或 者 后 面 的 fiilover 设 置 为 true 而 且 没 有 索引 能 匹配 上 正则 模式 的 话 ， 搜 索 这 里 设置 的 索引 。 
“ pattern: 如 果 interval 被 设置 成 除了 none 以 外 的 其 他 值 ， 就 需要 解析 这 里 设置 的 模式 ， 启 用 时 间 过 滤 规 则 ， 来 确定 请 求 哪些 索引 。 
“ warm fields: 是 否 需要 解析 映射 表 来 确定 字段 列表 。 


8. 其 余 


下 面 四 个 也 是 顶层 的 仪表 盘 配 置 项 : 


“failover” : false, 
"editable" : true, 
“style” : "dark" , 
“refresh” : false 


` falover: 真 假 值 ， 确 定 在 没有 匹配 上 索引 模板 的 时 候 是 否 使 用 indexdefault。 

. editable: 真 假 值 ， 确 定 是 否 在 仪表 盘 上 显示 配置 按钮 。 

style: “亮色 ” (light) 或 者 “暗色 ” (dark) 

refresh: 可 以 设置 为 全 se 或 者 其 他 Elasticsearch 支 持 的 时 间 表 达 式 (比如 10s，1m，1h) ， 用 来 描述 多 扩 和 触发 一 次 面板 的 数据 更 新 。 


9. 导 入 纲要 


默认 是 不 能 导入 纲要 的 。 不 过 在 仪表 盘 配 置 屏 的 控制 (Controls) 标签 里 可 以 开启 这 个 功能 ， 启 用 Local file 选 项 即 可 。 然 后 通过 仪表 盘 右上 角 加 载 图 标的 高 级 设置 ， 选 择 导入 文件 ， 就 可 以 导入 纲要 
了 。 


比如 之 前 提 到 的 莎士比亚 诗集 的 官方 提供 的 仪表 盘 ， 就 可 以 这 样 导 入 : 


* wget http://www.elasticsearch.org/guide/en/kibana/3.0/snippets/plays.json 


然后 选择 导入 plays.json 即 可 。 


或 者 通过 静态 仪表 盘 方式 使 用 ， 把 下 载 的 纲要 放 到 指定 位 置 : 


# mv plays.json kibana/src/app/dashboards//A/&ij F]http: //1ocalhost:8000/f/dashboard/file/plays.json 


然后 访问 http://localhost: 8000/#/dashboard/file/plays.json 地 址 也 能 看 到 同样 效果 。 


16.6.2 ”模板 化 template 仪 表盘 
Kibana 支 持 通过 模板 或 者 更 高 级 的 脚本 来 动态 地 创建 仪表 盘 。 你 先 创建 一 个 基础 的 仪表 盘 ， 然 后 通过 参数 来 改变 它 ， 比 如 通过 URL 插 入 一 个 新 的 请 求 或 者 过 滤 规 则 。 


模板 和 脚本 都 必须 存储 在 磁盘 上 ， 目 前 不 支持 存储 在 Elasticsearch 里 。 同 时 它们 也 必须 是 通过 编辑 或 创建 纲要 生成 的 。 所 以 ， 一 定 要 先 阅读 上 一 节 内 容 后 ， 再 看 本 节 。 


仪表 盘存 储 在 Kibana 安 装 目录 里 的 app/dashboards 子 目录 里 。 你 会 注意 到 这 里 面 有 两 种 文件 :json 文件 和 .js 文件 。 


json 文 件 就 是 模板 化 的 仪表 盘 。 模 板 示例 可 以 在 logstash.json 仪 表盘 的 请 求 和 过 滤 对 象 里 找到 。 模 板 使 用 handlebars 语 法 ， 可 以 让 你 在 json 里 插入 javascript 语 句 。URL 人 参数 存在 ARGS 对 象 中 。 下 面 是 
logstash.json 里 请 求 和 过 滤 服务 的 代码 片段 : 


“query” i E {ARGS . query NN“; 


: , 
“color” : “#7EB26D” , 
“pin” : false 
ps 0r sa 
"type" : “time”, 
"field" : "Qtimestamp' , 
"from" : ^"now-((ARGS.from || ” 24h *]J" , 


这 人 允许 我 们 在 URL 里 设置 两 个 参数 ，query 和 from。 如 果 没 设置 ， 默 认 值 就 是 | 后 面 的 内 容 。 比 如 说 ， 下 面 的 URL 就 会 搜索 过 去 7 天 内 status: 200 的 数据 : 


Qua 


千 万 注意 url#/dashboard/file/logstash.json 里 的 fe 字样: http://yoursetver/index.html&? /dashboard/file/logstash.jsonquery-status: 200&from-7d 


16.6.3 ”脚本 化 scripted 仪 表盘 


脚本 化 仪表 盘 比 模板 化 仪表 盘 更 加 强大 。 当 然 ， 功 能 强大 随 之 而 来 的 问题 就 是 构建 起 来 也 更 复杂 。 脚 本 化 仪表 盘 的 目的 就 是 构建 并 返回 一 个 描述 了 完整 的 仪表 盘 纲要 的 javascript 对 象 。 
app/dashboards/logstash.js 就 是 一 个 有 着 详细 注释 的 脚本 化 仪表 盘 示 例 。 这 个 文件 的 最 终结 果 和 logstash.json 一 致 ， 但 提供 了 更 强大 的 功能 ， 比 如 我 们 可 以 用 逗号 分 割 多 个 请 求 : 


http://yourserver/index.html#/dashboard/script/logstash.js?query=status: 403, 
status:404&from-7d 


这 会 创建 两 个 请 求 对 象 ，status: 403 和 status: 404 并 分 别 绘图 。 事 实 上 这 个 仪表 盘 还 能 接收 另 一 个 参数 split， 用 于 指定 用 什么 字符 串 切 分 。 


http://yourserver/index.html#/dashboard/script/logstash.js?query=status: 403! 
status:404&from-7d&split-! 


Ors 
千 万 注意 URIL#/dashboard/script/logstash.js 里 的 script 字 样 。 这 让 Kibana 解 析 对 应 的 文件 为 JavaScript 脚 本 。 


我 们 可 以 看 到 logstash.js 里 是 这 么 做 的 : 


// In this dashboard we let users pass queries as comma separated list to the query parameter. 
// Or they can specify a split character using the split aparameter 
// If query is defined, split it into a list of query objects 
// NOTE: ids must be integers, hence the parseInt () s 
if (! .isUndefined (ARGS.query) ) 
queries = .object ( .map (ARGS.query.split (ARGS.split||', ') , function (vk) { 
return [k,( T 

query: v, 

id: parseInt (k,10) , 
alias: v 


n; 
Ds 
} else ( 
// No queries passed? Initialize a single query to match everything 
queries = { 
0: ( 
query: '*', 
ids 0, 
} 
H 
} 


该 仪表 盘 可 用 参数 比 上 面 讲述 的 还 要 多 ， 全 部 参数 都 在 logstash.js 文 件 里 开始 的 注释 中 有 讲解 。 


16.7 ”认证 授权 


16.7.1 ”用 Nginx 实 现 基础 的 认证 


Kibana 3 作为 一 个 纯 静 态 文件 式 的 单 页 应 用 ， 可 以 运行 在 任意 主机 上 ， 却 要 求 所 有 用 户 的 浏览 器 ， 都 可 以 直 连 ELasticsearch 集 群 。 这 对 网 络 和 数据 安全 都 是 极为 不 利 的 。 所 以 ， 一 般 在 生产 环境 的 ELK 
stack， 都 是 采取 HTTP 代 理 层 的 方式 来 做 一 层 防护 。 最 简单 的 办 法 就 是 使 用 Nginx 代 理 配置 。 


Elasticsearch 官 方 也 提供 了 一 个 推荐 配置 : https://github.com/elastic/kibana/blob/3.0/sample/nginx.conf 


server ( 


listen *:80; 
server name kibana.myhost.org; 
access log /var/log/nginx/kibana.myhost.org.access.log; 


location / ( 
root /usr/share/kibana3; 
index index.html  index.htm; 

} 

location ~ ^/ aliases$ ( 
proxy pass http://127.0.0.1:9200; 
proxy read timeout 90; 

} 

location ~ ^/.*/ aliases$ { 
proxy pass http://127.0.0.1:9200; 
proxy read timeout 90; 

f 

location ~ ^/_nodes$ { 
proxy pass http://127.0.0.1:9200; 
proxy read timeout 90; 

} 

location ~ ^/.*/ search$ { 
proxy pass http://127.0.0.1:9200; 
proxy read timeout 90; 

$ 

location ~ ^/.*/_mapping { 
proxy_pass http://127.0.0.1:9200; 
proxy_read timeout 90; 

} 

# Password protected end points 

location ~ ^/kibana-int/dashboard/.*$ { 
proxy pass http://127.0.0.1:9200; 
proxy read timeout 90; 
limit except GET { 

proxy pass http://127.0.0.1:9200; 
auth basic “Restricted” ; 


auth basic user file /etc/nginx/conf.d/kibana.myhost.org.htpasswd; 


} 
l 
location ~ ^/kibana-int/temp.*$ { 
proxy pass http://127.0.0.1:9200; 
proxy read timeout 90; 
limit except GET ( 
proxy pass http://127.0.0.1:9200; 
auth basic “Restricted” ; 


auth basic user file /etc/nginx/conf.d/kibana.myhost.org.htpasswd; 


} 
$ 
} 


由 此 也 可 以 看 到 ，Kibana 3 实际 往 Elasticsearch 发 起 的 请 求 都 有 哪些 。 


然后 ， 在 同时 运行 了 Nginx 和 Elasticsearch 服 务 (建议 为 client 角 色 ) 的 这 台 服 务 器 上 ， 配 置 elasticsearch.ym| 为 : 


network.bind host: 127.0.0.1 
network.publish host: 127.0.0.1 
network.host: 127.0.0.1 


其 他 Elasticsearch 节 点 统一 关闭 HTTP 服 务 ， 配 置 elasticsearch.yml: 


http.enabled: false 


这 样 ， 所 有 人 都 只 能 从 Nginx 服 务 来 查询 Elasticsearch 服 务 了 。 从 Nginx 日 志 中 ， 我 们 还 可 以 审核 查询 请 求 的 语法 性 能 和 合理 性 。 


Qus 


改 配置 前 提 是 Logstash 采 用 nodeVtransport 协 议 写 入 数据 ， 如 果 使 用 http 协 议 的 ， 请 采 


16.7.2 用 Nodejs 实 现 基 于 CAS 的 认证 


CAs 是 社区 star 数 最 高 的 一 个 方案 ， 首 先 需要 准备 以 下 组 件 : 
“ Nginx: 仅仅 是 为 了 记录 日 志 ， 不 用 也 行 。 
: Node.js: 为 了 跑 kibana-authentication-proxy。 
* Kibana 3: https:/ /github.com/elastic/kibana/tree/kibana3 o 
* kibana-authentication-proxy: https:/ /github.com/fangli/kibana-authentication-proxy « 


配置 步骤 如 下 : 


1) nginx 配 置 8080 端 口 ， 反 向 代理 到 es 的 9200。 
2) git clone https://github.com/fangli/kibana-authentication-proxy。 


3) git clone https://github.com/elastic/kibana&&git checkout kibana3, 


4) 将 第 三 部 获取 的 kibana 目 录 软 链接 到 kibana-authentication-proxy 目 录 下 。 


5) 配置 kibana-authentication-proxy/config.js。 


可 能 有 如 下 参数 需要 调整 : 


用 iptables 防 护 ， 或 新 增 /_bulk 等 写 入 接口 的 代理 配置 。 


es_host # 这 里 是 nginx 地 址 

es port #nginx 的 8080 

listen port #node 的 监听 端口 ， 80 
listen host #node 的 绑 定 IP， 可 以 0.0.0.0 


cas server url #CAS 地 址 


6) 安装 kibana-authentication-proxy 的 依赖 ，npm install express 等 。 


7) 运行 node kibana-authentication-proxy/app.js. 


1. 关 键 性 代码 流程 


appjs 里 面 app.get ('/config.js', kibana3configjs) ; 返回 了 一 个 新 的 config.js， 不 是 用 的 kibana/config.js， 在 这 个 配置 里 面 ,调用 Elasticsearch 数 据 的 URL 前 面 加 了 一 个 _es 的 前 级。 


在 appjs 入 口 这 里 ， 有 两 个 关键 的 中 间 层 (我 也 不 知道 叫 什么 名 字 ) 被 注册 : 一 个 是 configureCas， 一 个 是 configureESProxy。 


一 个 请 求 来 的 时 候 ， 会 到 configureCas 判 断 是 不 是 已 经 登录 到 CAS， 没 有 的 话 就 转 到 cas 登 录 页 面 。 


configureESProxy 在 lib/es-proxy,js 里 ， 会 把 _es 打 头 的 请 求 (其 实 就 是 请 求 es 数据 的 请 求 ) 转发 到 真正 的 es 接口 那里 (我 们 这 里 是 Nginx) 。 
2. 请 求 路 径 


node (80) <=> nginx (8080) <=> es (9200) 


kibana-authentication-proxy 本 身 没有 记录 日 志 的 代码 ， 而 且 转 发 es 请 求 用 的 流 式 的， 并 不 能 记录 详细 的 request body。 所 以 我 们 就 用 Nginx 又 代理 一 层 记录 日 志 。 


16.7.3 ”用 Per| 实 现 认 证 和 用 户 授权 


社区 已 经 有 用 Nodejs 或 者 rubyonrails 写 的 kibana-auth 方 案 了 。 不 过 我 对 这 两 种 语言 都 不 太 擅 长 ， 只 会 写 一 点 点 Perl5 代 码 ， 所 以 我 选择 用 Mojolicious Web 开 发 框架 (http://mojolicio.us/) 来 实现 
我 自己 的 Kibana 认 证 鉴 权 。 


整套 方案 的 代码 以 Kbnauth 子 目录 形式 存在 于 我 的 Kibana 仓 库 中 ， 如 果 你 不 想 用 这 套 认证 方案 ， 照 旧 使 用 src 子 目录 即 可 。 事 实 上 ，kbnauth/public/ 目 录 下 的 静态 文件 我 都 是 通过 软 连 接 方式 指 到 src/ 
下 的 。 


1. 特 性 
这 套 方案 有 很 多 优势 ， 总 结 如 下 。 


(1) 全 局 透明 代理 


和 nodejs 实 现 的 那 套 方案 不 同 ， 我 这 里 并 没有 使 用 _es/ 这 样 附 加 的 路 径 。 所 有 发 往 Elasticsearch 的 请 求 都 是 通过 这 个 方案 来 控制 。 除 了 使 用 config.js.ep 模 版 来 定制 Elasticsearch 地 址 设置 以 外 ,方案 
还 会 仿造/_nodes 请 求 的 响应 体 ， 伪 造 的 响应 体 中 永远 只 有 运行 着 认证 方案 的 这 台 服 务 器 的 IP 地 址 。 


这 么 做 的 原因 是 我 的 Kibana 升 级 了 elastidjs 版 本 ， 新 版 本 默认 会 通过 这 个 API 获 取 nodes 列 表 ， 然 后 浏览 器 直接 轮 询 多 个 IP 获取 响应 。 


Qua 


Mojolicious 有 一 个 环境 变量 叫 max_message_size， 上 默认 是 10MB， 即 只 允许 代理 响应 大 小 在 10MB 以 内 的 数据 。 我 在 script/kbnauth 启 动 脚本 中 把 它 修改 成 了 0， 即 不 限制 。 如 果 你 有 这 方面 的 需求 ， 可 以 修改 
成 任意 你 想 要 的 阅 值 。 


(2) 使 用 kibana-auth Elasticsearch 索 引 做 鉴 权 


因为 所 有 的 请 求 都 会 发 往 代理 服务 器 ( 即 运行 着 认证 鉴 权 方案 的 服务 器 ) ， 每 个 用 户 都 可 以 有 自己 的 仪表 盘 空 间 ( 没 错 ， 这 招 是 从 kibana-proxy 项 目 学 来 的 ， 每 个 用 户 使 用 单独 的 kibana-int- 
$username 索 引 保 存 自己 的 仪表 盘 设置 ) 。 而 本 方案 还 提供 另 一 个 高 级 功能 : 还 可 以 通过 另 一 个 新 的 索引 kibana-auth 来 指定 每 个 用 户 所 能 访问 的 Elasticsearch 集 群 地 址 和 索引 列表 。 


给 “sri” 添 加 鉴 权 信息 的 命令 如 下 : 


$ curl -XPOST http://127.0.0.1:9200/kibana-auth/indices/sri -d '{ 
“prefix” :[ "logstash-sri" , "logstash-ops" ], 
"server" : "192.168.0.2:9200" 

y 


这 就 意味 着 “sri” 能 访问 的 ， 是 存在 “192.168.0.2: 9200" Ff] "logstash-sri-YYYY.MM.dd" ag "logstash-ops-YYYY.MM.dd" 索引 。 


Qus 


所 以 你 在 kbn_auth.conf 里 配置 的 eshost/esport， 其 实 并 不 意味 着 Kibana 数 据 的 来 源 ， 而 是 认证 方案 用 来 请 求 kibana-auth 信 息 的 地 址 ! 


(3) 使 用 Authen: : Simple 框 架 做 认证 


Authen: : Simple 是 一 个 很 棒 的 认证 框架 ， 支 持 非 常 多 的 认证 方法 。 比 如 : LDAP, DBI, SSH, Kerberos, PAM, SMB, NIS, PAM, ，ActiveDirectory 等 。 模 块 文档 
: https://metacpan.org/pod/Authen: : Simple 


z] 


默认 使 用 的 是 Passwd 方 法 。 也 就 是 用 htpasswd 命 令 行 在 本 地 生成 一 个 .htpasswd 文 件 存 用 户 名 密码 。 


如 果 要 使 用 其 他 方法 ， 比 如 用 LDAP 认 证 ， 只 需要 配置 kbn_auth.conf 文 件 就 行 了 : 


authen => { 
LDAP => { 
host => 'ad.company.com', 
binddn => 'proxyuser@company.com', 
bindpw => 'secret', 
basedn => 'cn-users,dc-company, dc-com', 
filter => “ (& (objectClass-organizationalPerson) (objectClass-user) (sAMAccountName-$s) ) 
h 
} 


可 以 同时 使 用 多 种 认证 方式 ， 但 请 确保 每 种 都 是 有 效 可 用 的 。 某 一 个 认证 服务 器 连接 超时 也 会 影响 到 其 他 认证 方式 超时 。 


2. 安 装 
该 方案 代码 只 有 两 个 依赖 : Mojolicious 框 架 和 Authen: : Simple 框 架 。 我 们 可 以 通过 cpanm 部 署 : 


curl http://xrl.us/cpanm -o /usr/local/bin/cpanm 
chmod +x /usr/local/bin/cpanm 


cpanm Mojolicious Authen::Simple::Passwd 


如 果 你 需要 使 用 其 他 认证 方法 ， 每 个 方法 都 需要 另外 单独 安装 。 比 如 使 用 LDAP 部 署 ， 就 再 运行 一 行 : cpanm Authen: : Simple: : LDAP 就 可 以 了 。 
Ors 


如 果 你 是 在 一 个 新 RHEL 系 统 上 初次 运行 代码 ， 你 可 能 会 发 现 有 报错 说 找 不 到 Digest: : SHA 模 块 。 这 个 模块 其 实 是 Petl 核 心 模块 ， 但 是 RedHat 公 司 把 所 有 的 Perl 核 心 模块 单独 打包 成 了 perl-core.tpm， 所 以 


你 得 先 运行 一 下 yum install-y perl-core 才 行 。 我 讨厌 RedHat! 


3. 运 行 


cd kbnauth 

# 开发 环境 监听 3000 端口 ， 使 用 单 进程 的 morbo 服务 器 调试 

morbo script/kbnauth 

# 生产 环境 监听 80 端口 ， 使 用 高 性 能 的 hypnotoad 服务 器 ， 具 体 端 口 在 kbn auth.conf 中 定义 
hypnotoad script/kbnauth 


现在 ， 打 开 浏 览 器 ， 就 可 以 通过 默认 的 用 户 名 /密码 : “sri/secr3t” 登 录 进 去 了 。 (sri 是 Mojolicious 框 架 的 作者 ， 感 谢 他 为 Perl5 社 区 提供 这 么 高 效 的 Web 开 发 框架 ) 


Qua 


这 时 候 你 虽然 认证 通过 进去 了 Kibana 页 面 ， 但 是 还 没有 赋 权 。 按 照 上 面 提 到 的 kipana-auth 命 令 操 作 ， 才 算 全 部 完成 。 


第 17 章 ”Kibana 3 源码 解析 


Kibana 3 能 成 为 ELK stack 风 摩 世界 的 最 大 推动 力 ， 其 优美 的 界面 与 简洁 的 代码 功 不 可 没 ， 所 以 很 有 必要 分 析 其 源 代码 。 


笔者 并 非 专业 的 前 端 工程 师 ， 对 Angularjs 框 架 也 处 于 入 门 水 准 ， 所 以 本 章 只 介绍 一 些 个 人 工作 中 涉及 的 地 方 ， 欢 迎 各 位 指正 。 本 章 主要 内 容 包括 : 


“ 源码 目录 结构 。 罗 列 Kibana 3 源码 目录 的 树 状 结构 ， 让 读者 了 解 其 概况 。 

“ 入口 和 模块 依赖 。 从 主页 代码 出 发 ， 厘 清 框架 代码 逻辑 。 

“ 控制 器 和 服务 。 介 绍 Kibana 3 利用 Angular.js 框 架 的 控制 器 和 服务 特性 编写 的 一 些 非常 有 用 的 功能 ， 在 后 续 二 次 开发 中 会 用 到 。 
“ 面板 指令 。 介 绍 配置 页 如 何 将 面板 添加 到 仪表 盘 。 

“ 面板 实现 。 介 绍 一 个 标准 面板 的 通用 实现 和 接口 函数 。 

- 用 facet 接 口 开 发 一 个 range panel， 演 示 一 个 range facet 请 求 的 面板 实现 实例 。 


“用 agg 接 口 开 发 一 个 percentile panel， 演 示 一 个 percentile agg 请 求 的 面板 实现 实例 。 其 更 大 的 意义 在 于 ， 解 决 了 Kibana 3 默认 无 法 支持 高 版 本 Elasticsearch 的 agg 查 询 的 底层 问题 。 


17.1 源码 目录 结构 


下 面 是 Kibana 3 源码 的 全 部 文件 的 tree 图 : 


' 配置 文件 : 


m config.js 


“主页 入 口 : 


|—— index.html 


- angular 程 序 目录 


— app 


' 程序 入 口 : 


app.js 


- 组 件 配置 目录 : 


Components | | extend-jquery.js | 攻 kbn.js | |—— lodash.extended.js 


- 定义 js 模块 依赖 : 


| |—— require.config.js ———— settings.js 


CEISSUE SE S: 


controllers | | all.js| | 一 一 dash.js | |—— dashLoader.js | | I—— pulldown.js | row.js 


“ 存放 脚本 化 及 模板 化 仪表 盘 : 


| 一 一 dashboards | | | 一 logstash.js | |—— 1logstash.json 


“ 实现 angular.directive 指 令 : 


confirmClick.js | L—— da: 


configModal.js 


addPanel.js | 


all.js| | 


| 一 一 directives | | arrayJoin.js 


表面 板 目录 : 


| 一 一 Panels 


“ 实现 一 个 具体 的 面板 (hits) : 


上 一 一 hits | editor.html | | |—— module.html | | module.js 


“ 挂件 页 面 : 


dashedit 


connectionFailed.html | I—— dashLoader.html | |—— dashLoaderShare.html | | |—— dashboard.html | 


I—— partials 


“ 实现 angular.service 服 务 : 


esVersion.js | fields.js Co filterSrv.js | 


all.js| |—— dashboard.js | 


services alertSrv.js | 


- 集中 存放 依赖 模块 库 文 件 : 


vendor 


一 目 了 然 ， 我 们 归纳 出 几 大 部 分 。 下 面 介绍 几 类 主要 文件 。 


17.2 ”入口 和 模块 依赖 


这 一 部 分 是 网 页 项 目的 基础 。 从 index.html 里 就 可 以 学 到 Angularjs 最 基础 的 常用 模板 语法 。 出 现 的 指令 有 ng-repeat、ng-controller、ng-include、ng-view、ng-slow、ng-click、ng-href， 以 及 


变量 绑 定 的 语法 {{tdashboard.current.**]}。 


index.html 中 ， 需 要 注意 js 的 加 载 次 序 ， 先 加 载 require.js， 然 后 加 载 require.config.js， 最 后 加 载 app。 整 个 Kibana 项 目 都 是 通过 require 方 式 加 载 的 。 而 具体 的 模块 和 模块 的 依赖 关系 ， 则 定义 在 
require.config.js 里 。 这 些 全 部 加 载 完 成 后 ， 才 启动 app 模 块 ， 也 就 是 项 目 本 身 的 代码 ， 如 下 所 示 : 


<script src= “vendor/require/require.js” ></script> 
<script src= “app/components/require.config.js” ></script> 
<script>require (['app'], function () {}) </script> 

«div ng-cloak ng-view»«/div» 


require.config.js 中 ， 主 要 分 成 两 部 分 配置 ， 一 个 是 paths， 一 个 是 shim。paths 用 来 指定 依赖 模块 的 导出 名 称 和 模块 js 文件 的 具体 路 径 。 而 shim 用 来 指定 模块 之 间 的 依赖 关系 。 比 方 说 ， 绘 制图 表 的 
js, Kibana 3 里 用 的 是 jquery.flot 库 。 其 首先 依赖 于 jquery 库 (通俗 地 说 ， 就 是 原先 普通 的 HTML 写 法 里 ， 要 先 加 载 jqueryjs 再 加 载 jquery.flot.js) . 


在 整个 paths 中 ， 需 要 单独 提 一 下 elasticjs: 'http://www.hzcourse.com/resource/readBook? 
path=/openresources/teach ebook/uncompressed/15426/OEBPS/Text/../vendor/elasticjs/elastic-angular-client'"。 这 是 捉 联 elastic.js 和 angularjs 的 文件 ， 其 中 实际 定义 了 一 个 angular.module 的 
factory， 名 叫 ejsResource。 后 续 我 们 在 Kibana 3 里 用 到 的 跟 Elasticsearch 交 互 的 所 有 方法 ， 都 在 这 个 ejsResource 里 。 


factory 是 angular 的 一 个 单 例 对 象 ， 创 建 之 后 会 持续 到 关闭 浏览 器 。Kibana 3 就 是 通过 这 种 方式 来 控制 所 有 的 图 表 是 从 同一 个 Elasticsearch 获 取 的 数据 。 


appjs 是 主 程序 入 口 。 下 面 拆 解 一 下 入 口 文件 。 


首先 是 定义 angular.module 以 及 一 些 常 量 , 我 们 最 关心 的 就 是 其 中 规定 了 对 应 Kibana 3 的 ES 最 低 版 本 号 : 


var app = angular.module ( 'kibana', []) , 
app.constant ('esMinVersion', 0.90. 9' ) 


然后 对 angular 的 $http 有 一 个 注入 ， 当 任意 $http 请 求 的 状态 码 为 0 时 ， 一 律 跳 转 到 /connectionFailed 页 面 。 状 态 码 为 0 是 XMLRequest 的 一 个 特殊 处 理 ， 即 请 求 未 达到 unreachable， 不 同 浏览 器 对 此 
的 定义 有 细微 的 区 别 : 


$httpProvider.interceptors.push (['$location', function ($1ocation) { 


return ( 
responseError: function (resp) { 
if (resp.status === 0) 


{ 
$location.path ( '/connectionFailed' ) ; 
console.log (resp) ; 

j 


nma 


具体 的 url 和 页 面 的 route 关 系 在 这 里 定义 。 大 家 可 以 发 现 ， 其 实 除 了 上 面 说 的 请 求 失败 以 外 ， 其 他 所 有 url 都 统一 用 app/partials/dashboard.html 模 板 。 当 然 ， 这 个 页 面 没 哈 看 头 ， 因 为 里 面 就 是 提供 
pulldown 和 row 的 div， 然 后 绑 定 到 对 应 的 controller 上 : 


$routeProvider 
.when ( '/connectionFailed', ( 
templateUrl: 'app/partials/connectionFailed.html', 


.when ('/dashboard', ( 


templateUrl: 'app/partials/dashboard.html', 


) 

.when ('/dashboard/:kbnType/:kbnlId', ( 
templateUrl: 'app/partials/dashboard.html', 

p 

.when ('/dashboard/ : konType/ : kbnId/:params', ( 
templateUrl: 'app/partials/dashboard.html' 

p 

.otherwise (( 
redirectTo: 'dashboard' 

D; 


后 续 还 会 生成 Kibana 3 下 面 的 其 他 名 字 空 间 ， 基 本 是 跟 目录 名 一 一 对 应 的 : 


..each ( 'controllers directives factories services filters'.split (' i 
function (type) { 
var module name = 'kibana. '+type; 


app.useModule (angular.module (module name, []) ) ; 
apps deps.push (module name) ; 
5 


最 后 ， 加 载 控制 器 和 辅助 指令 : 


require ([ 
'controllers/all', 
'directives/all', 
'filters/all' 
] 


appjjs 中 ， 定 义 了 整个 应 用 的 routes， 加 载 了 controller、directives 和 filters 里 的 全 部 内 容 。 


17.3 ”控制 器 和 服务 


controller 里 没 太 多 内 容 。Kibana 3 里 ，pulldown 其 实 跟 row 差 别 不 大 ， 下 面 代 码 里 最 关键 的 是 几 个 注入 : 


define (['angular','app','lodash'], function (angular, app, ) ( 
'use strict'; 7 
angular.module ( 'kibana.controllers' ) . controller ( 'RowCtrl', function ($scope, 
$rootScope, $timeout,ejsResource, querySrv) { 
var d= {ċ{ 
title: “Row” , 
height: “150px” , 
collapse: false, 
collapsable: true, 
editable: true, 
panels: [], 
notice: false 


..defaults ($scope.row,_d) ; 

$scope.init = function () ( 
$scope.querySrv - querySrv; 
$scope.reset panel () ; 

Fs 


$scope.init () ; 


service, 


service 跟 factory 的 概念 非常 类 似 ， 一 般 来 说 ，factory 用 来 共享 一 个 类 ， 而 service 用 来 共享 一 组 函数 功能 。 


Kibana 3 里 ， 比 较 有 用 和 常用 的 service 包 括 : dashboard、querySrv、filterSrv、fields、esVersion。 下 面 分 别 介 绍 。 


17.3.1 dashboard 


dashboardjs 里 提供 了 关于 Kibana 3 仪表 盘 的 读 写 操作 。 其 中 主要 是 提供 了 三 种 读 取 仪表 盘 布局 纲要 的 方式 ， 也 就 是 读 取 文 件 、 


XE: 


this.script load = function (file) { 
return $http (| 
url: "app/dashboards/" -file.replace (/N. (? ! js) /, "7" ) , 
method: “GET” , 
transformResponse: function (response) { 
/*jshint -W054 */ 
var _f = new Function ( 'ARGS','kbn', '_', 'moment', 'window', 'document', 'angular', 
'require', 'define','$','jQuery',response) ; 
return f ($routeParams,kbn, ,moment) : 
} 
}) ə then (function (result) { 
if (! result) { 
return false; 


i 
self.dash load (dash defaults (result.data) ) ; 
return true; B 
j,function () ( 
alertSrv.set ('Error', 
"Could not load «i»scripts/" +file+ “</i>. Please make sure it exists and 
returns a valid dashboard" , 
'error' ) i 
return false; 
D; 
H 


其 中 ， 注 入 了 $scope、ejsResource 和 querySrv。$scope 是 控制 器 作用 域内 的 模型 数据 对 象 ， 这 是 Angular 提 供 的 一 个 特殊 变量 。ejsResource 是 一 个 factory， 前 面 已 经 讲 过 。querySrv 是 一 个 


读 取 存 在 .kibana-int 索 引 里 的 数据 、 读 取 js 脚 本 。 下 面 是 读 取 js 脚 本 的 相 


可 以 看 到 ， 最 关键 的 是 new Function。 知 道 这 里 传 了 哪些 函数 进去 ， 也 就 知道 js 脚本 里 可 以 调用 哪些 内 容 了 。 


最 后 调用 的 dash_load 方 法 有 几 行 这 样 的 代码 : 


self.availablePanels = _.difference (config.panel names, 
..pluck ( .union (self.current.nav,self.current.pulldowns) , ‘type’ ) ) ; 
self.availablePanels = .difference (self.availablePanels,config.hidden panels) ; 


从 最 外 层 的 configjjs 里 读 取 了 panel_names 数 组 ， 然 后 取出 了 nav 和 pulldowns 用 过 的 panel， 剩 下 就 是 我 们 能 在 row 里 添加 的 panel 类 型 了 。 


17.3.2 querySrv 


querySrvjs 里 定义 了 跟 query 框 相关 的 函数 和 属性 ， 主 要 有 以 下 几 个 : 
' 一 个 是 color 列 表 。 
“ 一 个 是 queryTypes， 尤 其 是 topN， 可 以 看 到 topN 方 式 其 实 就 是 先 请 求 了 一 次 termsFacet， 然 后 把 结果 成 一 组 普通 的 query。 


: 一 个 是 ids 和 idsByMode。 之 后 绑 定 具体 query 的 时 候 ， 就 是 通过 这 个 函数 来 选择 的 。 


17.3.3 filterSrv 


filterSrvjs 跟 querySrv 相 似 ， 特 殊 的 是 以 下 两 个 函数 : 
“ toBjsObjs。 根 据 不 同 的 filter 类 型 调用 不 同 的 ejs 方 法 。 
“ timeRange。 在 histogram panel 上 拖 统 ， 会 生成 多 个 range 过 滤器 ， 且 都 是 时 间 。 这 个 方法 会 选择 最 后 一 个 类 型 为 time 的 包 ter， 作 为 实际 要 用 的 包 ter， 这 样 保证 请 求 Elasticsearch 的 是 最 后 一 次 拖 奥 选 定 的 时 


RE. 


17.34 fields 


fieldsjs 最 重要 的 作用 就 是 通过 mapping 接 口 获取 索引 的 字段 列表 ， 存 在 fieldslist 里 。 这 个 数组 后 来 在 每 个 panel 的 编辑 页 里 都 以 bs-typeahead= “fields.list” 的 形式 作为 文本 输入 时 的 自动 补 全 提 
示 。 在 table panel 里 ， 则 是 左 侧 栏 的 显示 来 源 。 


17.3.5 esVersion 


esVersion.js 里 提供 了 对 Elasticsearch 版 本 号 的 对 比 函数 。 之 所 以 专门 提供 这 个 service， 一 是 因为 不 同 版 本 的 Elasticsearch 接 口 有 变化 ， 比 如 我 自己 开发 的 percentile panel 里 就 esVersion 判 断 了 两 次 
版 本 ， 因 为 percentile 接 口 是 1.0 版 之 后 才 有 ， 而 从 1.3 版 以 后 返回 数据 的 结构 又 发 生 了 一 次 变动 。 二 是 因为 Elasticsearch 的 版 本 号 格式 比较 复杂 ， 有 点 又 有 字母 。 


174 ”面板 指令 


配置 页 添加 面板 到 仪表 盘 的 指令 。 下 面 分 别 介绍 这 些 面板 指令 。 


17.4.1 添加 面板 


前 面 在 讲 app/services/dashboard.js 的 时 候 ， 已 经 说 到 能 添加 的 面板 列表 是 怎么 获取 的 。 那 么 面板 是 怎么 加 上 的 呢 ? 


= 


同样 是 之 前 讲 过 的 app/partials/dashaboard.html 里 加 载 了 partials/roweditor.htmlI 页 面 。 这 里 有 一 段 : 


<form class= “form-inline” > 
«select class= “input-medium” ng-model= “panel.type” ng-options- “panelType for 
panelType in dashboard.availablePanels|stringSort” ></select> 
<small ng-show= “rowSpan (row) > 11” > 
Note: This row is full, new panels will wrap to a new line. You should add another row. 
</small> 
</form> 
«div ng-show- “! ( .isUndefined (panel.type) ) ”> 
«div add-panel- "{ {panel .type}}” ></div> 
«/div» 


这 个 add-panel 指 令 是 由 appy/directives/addPaneljs 提 供 的。 方法 如 下 : 


$scope.$watch ( 'panel.type', function () ( 
var type = $scope.panel.type; 
$scope.reset panel ( type) ; 


if (! .isUndefined ($scope.panel.type) ) ( 
$scope.panel.loadingEditor - true; 
$scope.require (['panels/'4$scope.panel.type.replace ( "." , “/” ) +'/module'], function () ( 
var template = '«div ng-controller- "'4$scope.panel.type*' " 


ng-include- "V'app/partials/paneladd.htmlN '" »«/div»'; 
elem.html ($compile (angular.element (template) ) ($scope) ) ; 
$scope.panel.loadingEditor = false; 
Ns 
} 
p; 


可 以 看 到 ， 其 实 就 是 请 求 了 对 应 的 panels/xxx/module.js， 然 后 动态 生成 一 个 div， 绑 定 到 对 应 的 controller 上 。 


174.2 ”展示 面板 


还 是 在 app/partials/dashaboard.html 里 ， 用 到 了 另 一 个 指令 kibana-panel: 


<div 
ng-repeat- " (name, panel) in row.panels|filter:isPanel" 
ng-cloak ng-hide- "panel.hide" 
kibana-panel type-'panel.type' resizable 
class= "panel nospace' ng-class- "('dragInProgress' :dashboard.panelDragging] 
style= "position:relative'  ng-style- "('width':!panel.span?'100$': ( (panel. 
span/1.2) *10) +'%'}” 
data-drop- "true" ng-model- "row.panels' data-jqyoui-options 
jayoui-droppable- "(index:$index,mutate:false,onDrop: 'panelMoveDrop!',onOver: 
'panelMoveOver (true) ',onOut:'panelMoveOut']" > 
«/div» 


当然 ， 这 里 面 还 有 resizable 指 令 也 是 自己 实现 的 ， 不 过 一 般 我 们 用 不 着 关心 这 个 代码 实现 。 


下 面 看 app/directives/kibanaPanel.js 里 的 实现 。 


这 里 大 多 数 逻 辑 跟 addPaneljs 是 一 样 的 ， 都 是 为 了 实现 一 个 指令 。 对 于 我 们 来 说 ， 关 注 点 在 前 面 那 一 段 HTML 字 符 串 ， 也 就 是 变量 panelHeader。 这 就 是 我 们 看 到 的 实际 效果 中 ，Kibana 3 每 个 
部 那个 小 图 标 工具 栏 。 仔 细 阅 读 一 下 ， 可 以 发 现 除了 每 个 面板 都 一 致 的 那些 span 以 外 ， 还 有 一 段 是 : 


'«span ng-repeat- "task in panelMeta.modals' class= “row-button extra ng-show- "task.show' »' + 
'«span bs-modal- "task.partial' class= “pointer” ><i ' + 
'bs-tooltip- "task.description' ng-class- "task.icon' class= "pointer" »«/i»«/span»'* 
P P g PI p 
'«/span»' 


Ej 


板 项 


IR] 


标 就 是 在 这 里 加 入 的 。 


也 就 是 说 ， 每 个 面板 可 以 在 自己 的 panelMeta.modals 数 组 里 定义 不 同 的 小 图 标 ， 弹 出 不 同 的 对 话 浮 层 。 我 给 table panel 二 次 开发 加 入 的 exportAsCsv 功 能 ， 


17.5 ”面板 实现 


首先 进入 app/panels/ 下 ， 每 个 目录 都 是 一 种 面板 。 入 口 都 是 固定 的 : module.js。 


下 面 以 stats pane| 为 例 (因为 我 最 开始 就 是 抄 的 stats 做 percentile， 只 有 表格 没有 图 形 ， 最 简单 ) 。 


每 个 目录 下 都 至 少 有 以 下 三 个 文件 : modulejs、module.html、editor.html。 下 面 分 别 介绍 。 


17.5.1 modulejs 


module.js 就 是 一 个 controller， 跟 前 面 讲 过 的 controller 写 法 其 实 是 一 致 的 。 在 $scope 对 象 上 ， 有 几 个 属性 是 面板 实现 时 一 般 都 会 有 的 : 
* Sscope.panelMeta: 这 个 前 面 说 过 ， 其 中 的 modals 用 来 定义 panelHeader。 
“$scope.panel: 用 来 定义 面板 的 属性 。 一 般 实现 上 会 有 一 个 预定 义 好 的 default 值 。 可 以 发 现 这 个 $scope.panel 其 实 就 是 仪表 盘 岗 要 里 面 说 的 每 个 面板 的 可 设置 值 ! 


然后 一 般 $scope.init () 是 这 样 的 : 


$scope.init = function () { 

$scope.ready - false; 

$scope.$on ( 'refresh', function () { 
$scope.get data () ; 

js 

$scope.get data () ; 


}; 


也 就 是 每 次 有 刷新 操作 ， 就 执行 get_data () 方法 。 这 个 方法 就 是 获取 Elasticsearch 数 据 ， 然 后 渲染 效果 的 入 口 。 


$scope.get data = function () { 
if (dashboard.indices.length === 0) { 
return; 


l 
$scope.panelMeta.loading = true; 
var request, 
results, 
boolQuery, 
queries; 
request - $scope.ejs.Request () ; 
$scope.panel.queries.ids = querySrv.idsByMode ($scope.panel.queries) ; 
queries = querySrv.getQueryObjs ($scope.panel.queries.ids) ; 
boolQuery = $scope.ejs.BoolQuery () ; 
.each (queries, function (q) { 
^ boolQuery = boolQuery.should (querySrv.toEjsObj (q) ) ; 
p; 
request = request 
.facet ($scope.ejs.StatisticalFacet ( 'stats' ) 
.field ($scope.panel.field) 
.facetFilter ($scope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
boolQuery, 
filterSrv.getBoolFilter (filterSrv.ids () ) 
) ) ) ) size (0) ; 
.each (queries, function (q) ( 
^ var alias - q.alias || q.query; 
var query = $scope.ejs.BoolQuery () ; 
query.should (querySrv.toEjsObj (q) ) ; 
request.facet ($scope.ejs.StatisticalFacet ( 'stats '*alias) 
.field ($scope.panel.field) 
.facetFilter ($scope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
query, 
filterSrv.getBoolFilter (filterSrv.ids () ) 


)3 

)3 
H; 
$scope.inspector = request.toJSON () ; 
results = $scope.ejs.doSearch (dashboard.indices, request) ; 
results.then (function (results) { 

$scope.panelMeta.loading = false; 

var value = results.facets.stats[$scope.panel.mode]; 

var rows = queries.map (function (q) { 


var alias = q.alias || q.query; 

var obj = .clone (q) ; 

obj.label = alias; 

obj.Label = alias.toLowerCase () ; // sort field 
obj.value = results.facets['stats '*alias]; 

ob]j .Value = results.facets['stats '*alias];// sort field 


return obj; 
D; 
$scope.data = { 
value: value, 
rOWS: rows 
H 


$scope.$emit ('render' ) ; 


H 


stats pane| 的 这 段 函 数 几乎 跟 基础 示例 一 样 ， 有 如 下 几 步 : 
1) 生成 Request 对 象 。 


2) 获取 关联 的 query 对 象 。 


3) 获取 当前 页 的 filter 对 象 。 


4) 调用 选 定 的 facets 方 法 ， 传 入 参数 。 


5) 如 果 有 多 个 query， 逐 一 构建 facets。 
6) 请 求 完成 ， 生 成 一 个 JSON 内 容 供 inspector 查 看 。 


7) 发 送 请 求 ， 等 待 异 步 回 调 。 


8) 回调 处 理 数据 成 绑 定 在 模板 上 的 $scope.data。 


9) 泻 染 页 面 。 


注意 ，stats/module.js 后 面 还 有 一 个 filter，terms/module.js 后 面 还 有 一 个 directive， 这 都 是 为 了 实际 页 面 效果 加 的 功能 ， 跟 Kibana 本 身 的 filter、directive 本 质 上 是 一 样 的 ， 就 不 单独 讲述 了 。 


17.5.2 module.html 


module.html 就 是 面板 的 具体 页 面 内 容 。 没 有 太 多 可 说 的 ， 大 概 框架 如 下 : 


«div ng-controller-'stats' ng-init- "init () ”> 
«table ng-style- "panel.style' class= “table table-striped table-condensed" 
ng-show- "panel.chart == 'table '" > 
<thead> 
<th>Term</th> <th>{{ panel.tmode == “terms_stats” ? panel.tstat : “Count” }} 
</th> <th>Action</th> 
</thead> 
«tr ng-repeat- "term in data" ng-show- "showMeta (term) ” > 
«td class= "terms-legend-term" »((term.label))«/td» 
«td» ( (term.data[0] [1] }}</td> 
</tr> 
</table> 
</div> 


主要 就 是 绑 定 controller 和 init 函 数 。 对 于 示例 的 stats， 里 面 的 data 就 是 module.js 最 后 生成 的 $scope.data。 


17.5.3 editor.html 


editor.html 是 panel 参 数 的 编辑 页 面 的 主要 内 容 ， 参 数 编辑 还 有 一 些 共同 的 标签 页 ， 是 在 Kibana 3 的 app/partials/ 里 ， 这 里 就 不 讲 了 。 


editor.html 里 ， 主 要 提供 对 $scope.panel 中 参数 的 修改 保存 操作 。 当 然 实际 上 并 不 是 所 有 参数 都 暴露 出 来 了 。 这 也 是 官方 说 Kibana 3 采用 仪表 盘 纲要 ， 比 通过 页 面 修改 更 灵活 细腻 的 原因 。 


editor.html 里 需要 注意 的 是 ， 为 了 每 次 变更 都 能 实时 生效 ， 所 有 的 输入 框 都 注册 到 了 刷新 事件 ， 所 以 一 般 是 这 样 : 


«select ng-change- "set refresh (true) ” class= “input-small” ng-model- "panel. 
format” ng-options- "f for f in ['number', 'float', 'money', 'bytes']" »«/select» 


set_refresh 函 数 是 在 module.js 里 定义 的 : 


$scope.set refresh = function (state) { 
$scope.refresh = state; 


H 


Kibana 3 源码 的 主体 分 析 就 是 这 样 了 ， 怎 么 样 ， 看 完 以 后 ， 大 家 有 没有 信心 也 做 些 二 次 开发 ， 甚 至 跟 grafana 一 样 ， 蔡 换 掉 esResource， 换 上 一 个 你 自己 的 后 端 数据 源 呢 ? 


17.6 用 facet 接 口 开发 一 个 range panel 


查看 响应 时 间 在 不 同 区 间 内 的 占 比 是 一 个 非常 常见 的 监控 和 SLA 需 求 ，Elasticsearch 对 此 有 直接 的 接口 支持 。 考 虑 到 Kibana 3 内 大 多 数 还 是 用 facet 接 口 ， 这 里 也 沿 


: http;//www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-facets-range-facet.html, 


range facet 本 身 的 使 用 非常 简单 ， 就 像 官 网 示例 那样 ， 直 接 用 curl 命 令 就 可 以 完成 调试 : 


# curl -XPOST http://localhost:9200/10gstash-2014.08.18/ search -d '( 
“query” : { 
"match all” : {} 
y 
"facets" : { 
“rangel” : { 
"range" { 
“field” : “resp ms”, 
“ranges” : T 
( “to” : 1009, 
{ “from” : 101, "to" : 500 }, 
{ "from" : 500 } 


不 过 在 Kibana 里 ， 就 不 要 再 自己 拼 JSON 发 请 求 了 。elastic.js 关 于 range facet 的 文档 见 http://docs.fullscale.co/elasticjs/ejs.RangeFacet.html。 


因为 range facet 本 身 比较 简单 ， 所 以 RangeFacet 对 象 支持 的 方法 也 比较 少 : 一 个 addRange 方 法 添加 ranges 数 组 ， 一 个 field 方 法 添加 field 名 称 。 


17.6.1 代码 实现 


面板 代码 的 主要 层次 和 方法 上 节 已 经 讲 过 。 在 二 次 开发 中 ， 完 全 可 以 复制 一 个 类 似 的 现 有 panel， 然 后 开始 编辑 。 比 如 本 小 节 预 备 开发 一 个 以 饼 图 展示 区 间 统 计 的 面板 ， 即 可 复制 terms 面 板 代码 : 


# cp -r src/app/panels/terms src/app/panels/ranges 
# sed -i 's/terms/ranges/g' src/app/panels/ranges/* 


terms 面 板 中 ,设计 有 fmode 和 tmode， 分 别 控制 terms 和 term_stats 时 的 参数 情况 ， 而 ranges 面 板 中 并 不 需要 ， 所 以 去 除 这 部 分 属性 ， 在 module.js 中 有 关 tmode 的 内 容 更 加 简单 。 


1. 构 建 请 求 

if ($scope.panel.tmode === 'ranges ') { 
rangefacet = $scope.ejs.RangeFacet ('ranges' ) ; 
// AddRange 


.each ($scope.panel.values, function (v) ( 
rangefacet.addRange (v.from, v.to) ; 
Ds 


然后 加 上 query 和 filter， 这 一 步 是 所 有 面板 的 实现 都 一 致 的 : 


request = request 
.facet (rangefacet 
.field ($scope.field) 
.facetFilter ($scope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
boolQuery, 
filterSrv.getBoolFilter (filterSrv.ids () ) 
))2). size (0) ; 


2. 组 织 结果 


function build results () { 
var k=0; ` 
scope.data = []; 
.each (scope.results.facets.ranges.ranges, function (v) { 
^ var slice; 
if (scope.panel.tmode === 'ranges ') { 
slice = ( label : [v.from,v.to], data : [[k,v.count]], actions: true); 
} 
scope.data.push (slice) ; 
k=k+1; 
D; 
Scope.data.push ((label:'Missing field', 
data: [[k, scope. results.facets.ranges.missing]],meta: "missing" color: '#aaa',opacity:0}) ; 
if (scope.panel.tmode = ' ranges’ ) ( 
Sscope.data.push ((label:'Other values', 
data: [[k*1, scope.results.facets.ranges.other]],meta: "other" ,color:'4444'!]) ; 
} 
} 


3. 区 间 范 围 配 置 编辑 


这 个 新 panel 的 实现 ， 更 复杂 的 地 方 在 配置 编辑 上 一 一 如 何 让 range 


围 值 支 持 自 定义 添加 和 填写 ?” 对 此 ， 设 计 一 个 $scope.panel.values 数 组 ， 用 于 计算 facet 的 数值 范 


。 数 组 元 素 包括 : 


[ei 


* from: range 范 围 的 起 始点 
* to: range 范 围 的 结束 点 。 


editor.html 里 Field 栏 由 普通 的 文本 输入 框 改 成 表格 输入 : 


«div class= “editor-option” > 
<label class= "small" >Field</label> 
<input type= “text” class= “input-small” bs-typeahead= “fields.list” 
ng-model= “panel.field” ng-change= “set_refresh (true) ” > 
</div> B 
«div class- "editor-row' » 
«table class= "table table-condensed table-striped' > 
«thead» 
«tr» 
«th»From«/th» 
«th»To«/th» 
«th ng-show- "panel.values.length > 1" »Delete«/th» 
«trs 
</thead> 
<tbody> 
<tr ng-repeat= “value in panel.values” > 
<td> 
<div class= “editor-option” > 


<input class= “input-small” type= “number” ng-model= “value. from” 
ng-change= “set_refresh (true) ” > 
</div> 7 
</td> 
<td> 


<div class= “editor-option” > 
<input class= “input-small” type= 
ng-change= “set_refresh (true) 
</div> T 
</td> 
<td ng-show= “panel.values.length > 1” > 
<i ng-click= “panel.values = _.without (panel.values, value) ; 
set refresh (true) " class= “pointer icon-remove” ></i> 
</td> T 
</tr> 
</tbody> 
</table> 
<button type= “button” class= “btn btn-success' ng-click- “add new value (panel) ; 
set refresh (true) " ><i class= "icon-plus-sign' ></i> Add value</button> 
</div> 
</div> 


number” ng-model- “value. to” 
> 


这 里 使 用 了 一 个 add new value 函数 ， 需 要 在 module.js 中 定义 : 


$scope.defaultValue = ( 

'from': 0; 

'to' : 100 
] 
$scope.add new value = function (panel) { 
panel.values.push (angular.copy ($scope.defaultValue) ) ; 
H 


4 面板 单 击 生成 的 filtering 条 件 


另 一 个 需要 注意 的 地 方 是 饼 图 出 来 以 后 ， 单 击 饼 图 区 域 自动 生成 的 filtersrv 内 容 。 一 般 的 面板 这 里 都 是 terms 类 型 的 filterSrv， 传 递 的 是 面板 的 label 值 。 而 我 们 这 里 label 值 显然 不 是 Elasticsearch 有 效 的 
terms 语 法 ， 还 好 filterSrv 有 range 类 型 (histogram 面 板 的 time 类 型 的 filterSrv 是 在 daterange 基 础 上 实现 的 ) ， 所 以 稍微 修改 就 可 以 了 ， 如 下 所 示 : 


$scope.build search = function (range,negate) { 


17.6.2 面板 效果 
最 终 效果 如 图 17-1 所 示 。 


属性 编辑 界面 效果 如 图 17-2 所 示 。 
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ranges panel 的 完整 代码 见 https://github.com/chenryn/kibana/src/app/panels/ranges。 


17.7 ”用 agg 接 口 开 发 一 个 percentile panel 


Kibana 3.1 中 有 一 个 面板 是 stats 类 型 ， 返 回 对 应 请 求 的 某 指定 数值 字段 的 数学 统计 值 ， 包 括 最 大 值 、 最 小 值 、 平 均值 、 方 差 和 标准 差 。 这 个 stats 图 表 是 利用 Elasticsearch 的 facet 功 能 来 实现 的 。 而 在 
Elasticsearch 1.0 版 本 以 后 ， 新 出 现 了 一 个 更 细致 的 功能 aggregation， 按 照 官 方 文档 所 说 ,会 慢 慢 地 彻底 替代 掉 facet。 具 体 到 1.1 版 本 的 时 人 息 ，aggregation 里 多 了 一 项 percentile， 可 以 具体 返回 某 指定 
数值 字段 的 区 间 分 布 情况 。 这 对 日 志 分 析 大 有 帮助 。 对 这 项 功能 ，Elasticsearch 官 方 也 很 得 意 地 专门 在 博客 上 写 了 一 篇 报道 “Averages can be misleading: try a percentile" , 


percentile agg 请 求 示例 如 下 : 


stash-2014.07.11/ search -d '{ 


本 节 讲 解 如 何 基于 Elasticsearch 的 percentile aggregation 接 口 实现 统计 聚合 展示 面板 。 其 他 aggregation 也 可 以 类 比 。 
和 上 一 节 实 现 facet 接 口 面板 相 比 ， 页 面 布 局 和 主体 逻辑 基本 一 致 。 其 难点 在 以 下 几 方 面 : 


* Kibana 3 使 用 了 社区 流行 的 elastic.js 第 三 方 库 作 为 基础 依赖 库 。 而 kibana/src/vendor/elasticjs/elastic.js 文 件 开 头 写 的 版 本 号 是 v1.1.1， 而 其 实 它 是 2013-08-14 发 布 的 。 具 体 加 上 aggregation 支 持 的 时 间 是 2014- 


03-16, 但 是 版 本 号 依然 是 v1.1.1! 所 以 在 官网 文档 看 到 1.1.1 版 的 agg 语 法 ， 其 实在 Kibana 里 都 用 不 了 。 


“ elastic.js 新 版 在 支持 agg 接 口 的 同时 ， 对 本 身 的 底层 依赖 也 做 了 大 幅度 改动 ， 和 Elasticsearch 的 实际 交互 已 经 改 用 官方 的 elasticsearch.js 库 ，elastic.js 本 身 相 当 于 只 是 做 一 个 封装 。 但 是 elasticsearch.js 本 身 目 录 


结构 复杂 ， 加 入 require.configjs 里 也 不 是 那么 容易 。 


这 里 有 两 种 解决 办 法 ， 如 下 所 示 。 


1) 直接 使 用 angularjs 框 架 的 $.http 对 象 ， 手 拼 JSON 请 求 体 ， 把 Kibana 当 做 curl 来 处 理 。 


request = ( 
'stats': ( 
'filter': JSON.parse ($scope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
boolQuery, 
filterSrv.getBoolFilter (filterSrv.ids () ) 
) 
). toString () , true), 
'aggs': { 
'stats': ( 
'percentiles': ( 
'field': $scope.panel.field, 
'percents': $scope.modes 
} 
} 
} 
} 
H 
$.each (queries, function (i, q) ( 
var query = $scope.ejs.BoolQuery () ; 
query.should (querySrv.toEjsObj (q) ) ; 
var qname = 'stats 'ti; 
var aggsquery = {}; 
aggsquery[qname] = ( 
'percentiles': ( 
'field': $scope.panel.field, 
'percents': $scope.modes 
} 
H 
request[qname] = ( 
'filter': JSON.parse ($scope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
query, 
filterSrv.getBoolFilter (filterSrv.ids () ) 
) 
} » toString () , true), 
'aggs': aggsquery 
H 
D; 
$scope.inspector = angular.toJson ((aggs:request],true) ; 
results = $http ({ 
url: config.elasticsearch + '/' + dashboard.indices + '/ search?size-0', 
method: “POST” , T 
data: { aggs: request } 
D; 


2) 统一 升级 整个 Kibana 3 的 基础 依赖 库 版 本 ， 然 后 采用 agg 接 口 方法 。 


request = $scope.ejs.Request () ; 
$scope.panel.queries.ids = querySrv.idsByMode ($scope.panel.queries) ; 
queries = querySrv.getQueryObjs ($scope.panel.queries.ids) ; 
boolQuery = $scope.ejs.BoolQuery () ; 
..each (queries, function (q) ( 
boolQuery = boolQuery.should (querySrv.toEjsObj (q) ) ; 
D; 
var percents =  .keys ($scope.panel.show) ; 
request = request 
.aggregation ( 
$scope.ejs.FilterAggregation ( 'stats' ) 
.filter (Sscope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
boolQuery, 
filterSrv.getBoolFilter (filterSrv.ids () ) 


) 
»y 
.aggregation ($scope.ejs.PercentilesAggregation ( 'stats' ) 
.field ($scope.panel.field) 
-percents (percents) 
.compression ($scope.panel.compression) 
) 


). size (0) ; 


EF 要 需 提供 一 个 $scope.panel.modes 数 组 即 可 。 不 歼 述 。 


页 面 参 数 上 ， 根 据 percentile 的 请 求 参 数 需 


17.7.1 ”代码 实现 要 点 


1.Elasticsearch 1.1 和 1.3 版 本 的 返回 结果 集 层次 变动 


percentile aggregation 是 Elasticsearch 从 1.1.0 开 始 新 加 入 的 实验 性 功能 ， 而 且 在 1.3.0 之 后 其 返回 的 数据 结构 发 生 了 变动 ， 所 以 代码 中 对 Elasticsearch 的 版 本 要 做 判断 和 兼容 性 处 理 。 


Kibana 3 提供 了 一 个 service 叫 esVersion， 所 以 我 们 可 以 直接 这 样 : 


module.controller ( 'percentiles', function ($scope, querySrv, dashboard, 
filterSrv, $http, esVersion) ( 


results.then (function (results) ( 
$scope.panelMeta.loading = false; 
esVersion.gte ('1.3.0' ) 。 then (function (is) { 


if (is) ( 
var value = results.aggregations.stats['stats']['values'][$scope.panel.mode*'.0']; 
} eise ( 
esVersion.gte ( '1.1.0' ) . then (function (is) ( 
i£ (18) { 


var value = results.aggregations.stats['stats'] [$scope.panel.mode+'.0']; 


2. 浮 点 数 排序 
percentile aggregation 返 回 的 数据 中 ， 强 制 保留 了 百分数 的 小 数 点 后 一 位 ， 这 叶 致 在 js 处 理 中 会 把 小 数 点 当做 是 属性 调用 的 操作 符 ，Kibana 提 供 的 表 头 点 击 自动 排序 表格 数据 功能 也 就 失效 了 ， 所 以 
需要 替换 掉 sort_field 里 的 小 数 点 。 


modulejs 中 : 


var rows = queries.map (function (q, i) ( 


var alias = q.alias || q.query; 

var obj = .clone (q) ; 

obj .label = alias; 

obj .Label = alias.toLowerCase () ; // sort field 


obj.value = results.aggregations['stats '4i]['stats '*i]['values']; 
obj .Value = results.aggregations['stats '*i]['stats '*i] 
['values']; // sort field 
var V - {} 
for ( var k in obj.Value ) ( 
var v = obj.Value[k]; 
k = k.replace ( '.',' ) ; 
_V[k] = v; 


obj .Value = V; 
return obj; . 

D; 

$scope.data = { 
value: value, 
rOWS: rows 

H 


$scope.$emit ( ‘render’ ) ; 


module.htmlra : 


<thead> 
<tr> 
«th»«a href= "" ng-click- "set sort ( ‘label’ ) " ng-class- "('icon-chevron-down': 
panel.sort field == 'label' && panel.sort reverse == true, 'icon-chevron-up': 
panel.sort field == 'label' && panel.sort reverse 一 false]" > 


[(panel.label name]) «/a»«/th» 
«th ng-repeat- "stat in modes” ng-show- "panel.show[stat]" > 


<a href= 
ng-click= “set_sort (stat) ” 
ng-class- "('icon-chevron-down': panel.sort field == stat.replace ( '.','' ) 

&& panel.sort reverse == true, 'icon-chevron-up': panel.sort field == 
stat.replace ( '.','' ) && panel.sort reverse == false)" 5 

((stat))$ 

«/a» 

«/th» 

«/tr» 
</thead> 


3.query alias 的 中 文 支持 


目前 Kibana 里 都 是 以 alias 形 式 来 区 分 每 一 个 子 请 求 的 ， 具 体内 容 是 var alias=q.alias|lq.query; ， 即 在 页 面 上 搜索 框 里 写 的 查询 语句 或 者 是 搜索 框 左 侧 色彩 设置 菜 和 


BER Legend value, 


比如 我 的 场景 下 ，q.query 是 “xff: 10.5.16.*” ，q.alias 是 “教育 网 访问 ”， 那 么 最 后 发 送 的 请 求 


同样 的 写法 迁移 到 aggregation 上 就 完全 不 可 解析 了 ， 服 务 器 会 返 


Oez 


n 


这 条 过 滤 项 的 facets_name 就 叫 “stats 教育 网 访问 ”。 


一 条 报错 : aggregation_name 只 能 是 字母 、 数 字 、 或 者 -四 种 。 


这 里 比较 怪 的 是 抓 包 看 到 facet 其 实 也 报错 说 请 求 内 容 解 析 失 败 ， 但 是 居然 同时 返回 了 结果 ， 只 能 猜测 目前 是 处 在 一 种 兼容 状态 。 


于 是 这 里 稍微 修改 了 一 下 逻辑 ， 把 queries 数 组 的 .each 改 用 $.each， 这 样 回调 函数 里 不 仅 返 回 数组 元 素 ， 还 返回 数组 下 标 ， 下 标 一 定 是 数字 ， 就 可 以 以 数组 下 标 作为 aggregation_name 了 。 后 


结果 的 queries.map 同 样 以 下 标 来 获取 即 可 : 


$.each (queries, function (i, q) ( 
var query = $scope.ejs.BoolQuery () ; 
query.should (querySrv.toEjsObj (q) ) ; 
var qname = 'stats 'ti; 
request.aggregation ( 
$scope.ejs.FilterAggregation (qname) 
.filter ($scope.ejs.QueryFilter ( 
$scope.ejs.FilteredQuery ( 
query, 
filterSrv.getBoolFilter (filterSrv.ids () ) 


) 
)) 
.aggregation ($scope.ejs.PercentilesAggregation (qname) 
.field ($scope.panel.field) 
-percents (percents) 
.compression ($scope.panel.compression) 
) 
E? 
Di 
$scope.inspector = request.toJSON () ; 
results = $scope.ejs.doSearch (dashboard.indices, request) ; 


17.7.2 [UR 


最 终 的 percentile 面 板 界面 与 stats 面 板 界面 类 似 ， 如 图 17-3 所 示 。 


处 理 


运营 商 酮 应 时 间 区 同 


图 17-3 percentile panel 效 果 


percentile panel 的 完整 代码 见 https://github.com/chenryn/kibana/src/app/panels/percentiles。 


第 18 章 Kibana 4 


Kibana 4 是 Elastic.co 一 次 密 新 的 重 构 产品 。 在 操作 界面 上 ， 有 一 定 程度 的 对 Splunk 的 模仿 ， 跟 Kibana 3 相 比 则 是 颠覆 性 的 改变 。 原 有 Kibana 3 上 的 操作 经 验 ， 几 乎 无 法 自然 带 入 到 Kibana 4 中 ， 所 以 
本 章 会 从 以 下 几 方 面 介绍 Kibana 4: 


“ 安装 、 配 置 和 运行 。Kibana 4 不 再 是 纯 静 态 HTML 页 面 产品 ， 所 以 本 节 先 介绍 Kibana 4 的 安装 部 署 方法 ， 然 后 演示 其 主要 页 面 的 效果 ， 给 读者 一 个 基本 印象 。 

“ 生产 环境 部 署 。 介 绍 Kibana 4 在 Nginx 代 理 和 Shield 权 限 控制 方面 的 配置 方法 。 

* discovet 功 能 。 介 绍 Kibana 4 上 Discovert 标 签 页 的 使 用 。 

“ 各 visualize 功 能 。 介 绍 Kibana 4 上 Visualize 标 签 页 的 使 用 ， 重 点 关注 各 种 可 选 可 视 化 图 表 的 配置 和 效果 。 

* dashboard 功能。 介绍 Kibana 4 上 Dashboard 标 签 页 的 使 用 。 

“setting 功 能 。 介 绍 Kibana 4 上 Setting 标 签 页 的 使 用 。 

- 设置 kibana 服 务 器 属性 。 在 服务 器 端 方面 ，Kibana 4 也 有 一 些 可 配置 项 ， 可 以 大 概 类 比 于 Kibana 3 时 的 configjs， 本 节 对 此 稍 作 介绍 。 

“ 常用 sub agg 示 例 。 没 有 了 Kibana 3 固定 的 panel 效 果 ，Kibana 4 基于 Elasticsearch 的 sub agg 可 以 做 到 更 灵活 的 控制 ， 本 节 以 几 个 实际 的 日 志 场景 ， 演 示 如 何 使 用 sub agg 构 造 Kibana 4 的 可 视 化 。 


* Kibana 报 表 的 快速 实现 。 介 绍 一 种 通过 phantomjs 页 面 截屏 功能 ， 完 成 长 期 历史 报表 的 方案 。 


18.1 安装、 配置 和 运行 


Kibana 4 安装 方式 依然 简单 ， 几 分 钟 内 就 可 以 死 安装 好 Kibana 然 后 开始 探索 你 的 Elasticsearch 索 引 数 据 。 和 使 用 Kibana 3 时 类 似 ， 也 需要 预备 好 一 个 Elasticsearch 集 群 ， 不 过 ， 这 次 ， 需 要 确保 
Elasticsearch 全 集群 所 有 节点 (包括 client 节 点 ) 版 本 号 至 少 大 于 等 于 1.4.4. 版 。 


如 果 你 的 Elasticsearch 是 被 Shield 保 护 着 的 ， 阅 读 稍 后 生产 环境 部 署 章 节 相关 内 容 学 习 额 外 的 安装 说 明 。 否 则 ， 普 通 情况 下， 按照 下 面 说 明 足 以 完成 Kibana 4 的 初次 使 用 了 。 


安装 并 启动 Kibana 4 的 步骤 如 一 : 
1) 首先 从 http://www.elasticsearch.org/overview/kibana/installation/ 下 载 对 应 平台 的 Kibana 4 二 进 制 包 
2) 解压 .zip 或 tar.gz 压 缩 文件 


3) 在 安装 目录 里 运行 : bin/kibana (Linux/MacOSX) 或 bin\kibana.bat (Windows) 


完毕 ! Kibana 现 在 运行 在 你 本 机 5601 端 口 了 。 


1. 让 Kibana 连 接 到 Elasticsearch 


在 开始 用 Kibana 之 前 ， 你 需要 告诉 它 你 打算 探索 哪个 Elasticsearch 索 引 。 第 一 次 访问 Kibana 的 时 候 ， 你 会 被 要 求 定 义 一 个 index pattern 用 来 匹配 一 个 或 者 多 个 索引 名 。 好 了 。 这 就 是 你 需要 做 的 全 部 
工作 。 以 后 你 还 可 以 随时 从 Settings 标 签 页 添加 更 多 的 index pattern, 


默认 情况 下 ，Kibana 会 连接 运行 在 localhost 的 Elasticsearch。 要 连接 其 他 Elasticsearch 实 例 ， 修 改 kibana.yml 里 的 Elasticsearch URL， 然 后 重启 Kibana。 如 何在 生产 环境 下 使 用 Kibana， 阅 读 生产 环 


境 部 署 章节 。 


要 从 Kibana 访 问 的 Elasticsearch 索 引 的 配置 方法 : 


1) 从 浏览 器 访问 Kibana 界 面 。 也 就 是 说 访问 比如 localhost: 5601 或 者 http://YOURDOMAIN.com: 5601。 在 初次 使 用 时 ， 会 跳 转 到 如 下 图 18-1 所 示 的 页 面 。 


2) 指定 一 个 可 以 匹配 一 个 或 者 多 个 Elasticsearch 索 引 的 index pattern。 默 认 情况 下 ，Kibana 认 为 你 要 访问 的 是 通过 Logstash 导 入 Elasticsearch 的 数据 。 这 时 候 你 可 以 用 默认 的 logstash-* 作 为 你 的 
index pattern。 通 配 符 (*) 匹配 索引 名 中 零 到 多 个 字符 。 如 果 你 的 Elasticsearch 索 引 有 其 他 命名 约定 ， 输 入 合适 的 pattern。pattern 也 开始 是 最 简单 的 单个 索引 的 名 字 。 


3) 选择 一 个 包含 了 时 间 戳 的 索引 字段 ， 可 以 用 来 做 基于 时 间 的 处 理 。Kibana 会 读 取 索 引 的 映射 ， 然 后 列 出 所 有 包含 了 时 间 戳 的 字段 ( 译 者 注 : 实际 是 字段 类 型 为 date 的 字段 ， 而 不 是 “看 起 来 像 时 间 
戳 ” 的 字段 ) 。 如 果 你 的 索引 没有 基于 时 间 的 数据 ， 关 闭 Index contains time-based events 参 数 。 


4) 如 果 一 个 新 索引 是 定期 生成 ， 而 且 索 引 名 中 带 有 时 间 截 ， 选 择 Use event times to create index names 选 项 ， 然 后 再 选择 Index pattern interval。 这 可 以 提高 搜索 性 能 ，Kibana 会 至 搜索 你 指定 的 
时 间 范 围 内 的 索引 。 在 你 用 Logstash 输 出 数据 给 Elasticsearch 的 情况 下 尤其 有 效 。 


Configure an index pattern 


In order to use Kibana you must configure at least one index pattern. index pattems are used to identify the Elascsearch index to run search and analytics against. 
They are aiso used to configure fieids. 


index name or pattern 
Patterns aliow you to define dynamic index names using * as a wiidcard. Example: logstash-* 


图 18-1 创建 索引 模式 


5) 点 击 Create 添 加 index pattern。 第 一 个 被 添加 的 pattern 会 自动 被 设置 为 默认 值 。 如 果 你 有 多 个 index pattern 的 时 候 ， 你 可 以 在 Settings>lndices 里 设置 具体 哪个 是 默认 值 。 


2. 探 索 数 据 


配置 索引 模式 后 ， 默 认 打 开 Kibana 4 会 出 现在 一 个 叫做 Discover 的 标签 页 ， 在 这 个 类 似 Kibana 3 的 logstash dashboard 的 页 面 上 ， 我 们 可 以 提交 搜索 请 求 ， 过 滤 结果 ， 然 后 检查 返回 的 文档 里 的 数据 ， 
如 下 图 18-2 所 示 。 


默认 情况 下 ，Discover 页 会 显示 匹配 搜索 条 件 的 前 500 个 文档 ， 页 面 下 拉 到 底部 ， 会 自动 加 载 后 续 数 据 。 你 可 以 修改 时 间 过 滤器 ， 拖 搜 直方 
数据 ， 详 细 说 明 见 稍 后 的 18.3 节 “Discover 功 能 。” 


IR] 


下 钻 数据 ， 查 看 部 分 文档 的 细节 。Discover 页 上 如 何 探索 


3. 在 Visualize 页 转换 数据 成 图 表 


IR] 


Visualization 标 签 页 用 来 为 你 的 搜索 结果 构造 可 视 化 。 每 个 可 视 化 都 是 跟 一 个 搜索 关联 着 的 。 比 如 ， 我 们 可 以 基于 前 面 那个 搜索 创建 一 个 展示 每 周 流量 的 直方 


。Y 轴 显示 流量 。X 轴 显示 时 间 。 而 添加 


一 个 子 聚合 ， 我 们 还 可 以 看 到 每 小 时 排名 前 三 的 结果 。 配 置 界面 如 图 18-3 所 示 。 


4. 在 Dashboard 页 创建 定制 自己 的 仪表 盘 


还 可 以 保存 并 分 析 可 视 化 结果 ， 然 后 合并 到 Dashboard 标 签 页 上 以 便 对 比分 析 。 比 如 说 ， 我 们 可 以 像 图 18-4 中 展示 的 那样 创建 一 个 含有 多 个 可 视 化 数据 的 仪表 盘 : 


type: mwaibo wabinf AND responsatimo:s2 a * 


© Last 25 minutas 


Septembar 2nd 2015, 10:22:08 086 - Septembar 2nd 2015, 10:37:08.986 — by 30 seconda. 


10,00 


162320 10240 102590 102600  :02^00 302800 10:2200 10300 1031:00 103200 — 102X*00 1034:00 103500 1036:00 1037300 
Gimestamp per 30 seconcs 
^ 


Time + .souros 
* September 2nd 28015, 10:37:06.000 — erinertamp; September 2nd 2015, 10:37:06.000 nosti web657.relbo.tc.siaanode.com eléwai wei 3333.2001 
fremstring: 10540953018 logweraion: @ uaerzame: 5643933347 eliestip: 117.275.17.736 eid: 5643933847 
errorcode: 1040002 respousetime: 2.002 xretetatus: FAIL uzrlpath: /reviem/userreviemlist.]son wrelagga: uid-$64 


3933847&countzz0 — 1d: AU-L6j$«5glJoc4)neypy  typer Peio weblaf index: logstosh-nweibo-?815.09.0? pretransfer 
LJ 


- ewssect: © dme me: © tartteneefer-pretranefaer: PH atectte-stacttcans far: © totaíloewecute: 


»  Septewber Zr 2015, 10:37:05.000 — geimestamp: Sopterbor Znd Z015, 18:37:05.00€0 höst: webllé.mweibo.tc.sinanode.com elm: wai 5421 


Éremstring: 10540903010 1logversion: 0 usersame: cookievi elientip: 112.224.19.60 uid: 1137225774 
errorcode: 1040007 respoumetima: 2 rwtwtatus: FAIL wrlpaths /review/userreviewllst.json uwrhmrgs: uids1137775 
774&count-20 id: AJ-L&jAMglJoc&JmoxPG type: mweibe wobinf  imdex: logstazh-wweibo-2815.09.02 pretrwnsfer 二 


eoaheaet: A äna nas C saterttennafer-pretrassfer: (O execute-starttrasafen: 0 toral-ewecute: À comment es: A 


September zrd 2815, 10:37:05.000 — Quimestamp: Septerber 2nd 2015, 18:37:05.000 host: webülü.mwmeibo.tc.simanode.con eldwmi wai 3333.2001 


图 18-2 Kibana 4 首页 


2013-11-04 1600 2013-11-08 1600 2913-11-08 1600 2013-11.07 1620 2013-11-08 1600 2013-11-00 16.CO 
Gjourneystart per hour 
^ 


图 18-3 Visualize 4] 


kibana 一 一 ~ 
TFL: Dashboard — 


TFL: Weekdy Oyster Card Use by Tube/Train per Hour TFL Top 3 Busiest Stations per Hour 


LI 


Alla. 


2013-11-04 16:00 2013.1 1-08 16:00 2013-11-08 16:00 2019-11-04 1600 — 201) 7908 1600 — 2013-11-08 1000 
Gjourneystart per hour Qjourneystart per hour 


" . 
Tien by MaQuest 一 Map data © Open Sirserlap cortributum, CC -8A 
^ 


图 18-4 dashboard 46] 


182 ”生产 环境 部 署 


Kibana 4 是 一 个 完整 的 Web 应 用 。 使 用 时 ， 你 需要 做 的 只 是 打开 浏览 器 ， 然 后 输入 你 运行 Kibana 的 机 器 地 址 然后 加 上 端口 号 ， 比 如 : http://localhost: 5601 或 者 http://YOURDOMAIN.com: 
5601。 


但 是 当 你 准备 在 生产 环境 使 用 Kibana 4 的 时 候 ， 比 起 在 本 机 运行 ， 就 需要 多 考虑 一 些 问题 : 


- 在 哪 运行 Kibana。 
' 是 否 需要 加 密 Kibana 出 入 的 流量 。 


“ 是 否 需要 控制 访问 数据 的 权限 。 


18.2.1 Nginx 代 理 配 置 


因为 Kibana 4 不 再 是 Kibana 3 那 种 纯 静 态 文件 的 单 页 应 用 ， 所 以 其 服务 器 端 是 需要 消耗 计算 资源 的 。 因 此 ， 如 果 用 户 较 多 ，Kibana 4 确实 有 可 能 需要 进行 多 点 部 署 ， 这 时 候 ， 就 需要 用 Nginx 做 一 层 代 
理 了 。 


和 Kibana 3 相 比 ，Kibana 4 的 Nginx 代 理 配 置 倒是 简单 许多 ， 因 为 所 有 流量 都 是 统一 配置 的 。 下 面 是 一 段 包含 入 口 流量 加 密 、 简 单 权限 控制 的 Kibana 4 代理 配置 : 


upstream kibana4 ( 
server 127.0.0.1:5601 fail timeout-0; 
} 


server { 


listen *:80; 

server name kibana server; 

access log /var/log/nginx/kibana.srv-log-dev.1log; 

error log /var/log/nginx/kibana.srv-log-dev.error.log; 
ssl on; 

ssl certificate /etc/nginx/ssl/all.crt; 


ssl certificate key  /etc/nginx/ssl/server.key; 
location / { 一 

root  /var/www/kibana; 

index index.html index.htm; 


location ~ ^/kibana4/.* ( 


proxy pass http://kibana4; 

rewrite ^/kibana4/ (. *)  /$1 break; 

proxy set header X-Forwarded-For $proxy add x forwarded for; 
proxy set header Host $host; B B 
auth basic "Restricted" ; 


auth basic user file /etc/nginx/conf.d/kibana.myhost.org.htpasswd; 


如 果 用 户 够 多 ， 当 然 你 可 以 单独 跑 一 个 Kibana 4 集群 ， 然 后 在 upstream 配 置 段 中 添加 多 个 代理 地 址 做 负载 均衡 。 


18.2.2 配置 Kibana 和 shield 一 起 工作 


Nginx 只 能 加 密 和 管理 浏览 器 到 服务 器 端的 请 求 ， 而 Kibana 4 到 ELasticsearch 集 群 的 请 求 ， 就 需要 由 Elasticsearch 方 面 来 完成 了 。 如 果 你 在 用 Shield 做 Elasticsearch 用 户 认证 ， 你 需要 给 Kibana 提 供用 


和 凭证， 这 样 它 才 能 访问 .kibana 索 引 。Kibana 用 户 需 要 由 权限 访问 .kibana 索 引 里 以 下 操作 : 


'.kibana': 

- indices:admin/create 

- indices:admin/exists 
indices:admin/mapping/put 
indices:admin/mappings/fields/get 
indices:admin/refresh 
indices:admin/validate/query 
indices:data/read/get 
indices:data/read/mget 
indices:data/read/search 
indices:data/write/delete 
indices:data/write/index 
indices:data/write/update 
indices:admin/create 


更 多 配置 Shield 的 内 容 ， 请 阅读 官网 的 Shield with Kibana 4 文档 : https://www.elastic.co/guide/en/shield/current/kibana.html* using kibana 4 with shield, 


配置 Kibana 4 的 赁 证， 设置 kibana.yml 里 的 kibana_elasticsearch_username 和 kibana_elasticsearch_password 选 项 即 可 :: 


# If your Elasticsearch is protected with basic auth: 
kibana elasticsearch username: kibana4 
kibana elasticsearch password: kibana4 


18.2.3 ”开启 SSL 


Kibana 同 时 支持 对 客户 端 请 求 以 及 Kibana 服 务 器 发 往 Elasticsearch 的 请 求 做 SSL 加 密 。 


要 加 密 浏 览 器 (或 者 在 Nginx 代 理 情况 下 ，Nginx 服 务 器 ) 到 Kibana 服 务 器 之 间 的 通信 ， 配 置 kibana.yml 里 的 ss|_key file 和 ssl_cert_ file 参数: 


# SSL for outgoing requests from the Kibana Server (PEM formatted) 
ssl key file: /path/to/your/server.key 
ssl cert file: /path/to/your/server.crt 


如 果 你 在 用 Shield 或 者 其 他 提供 HTTPS 的 代理 服务 器 保护 Elasticsearch， 你 可 以 配置 Kibana 通 过 HTTPS 方 式 访问 Elasticsearch， 这 样 Kibana 服 务 器 和 Elasticsearch 之 间 的 通信 也 是 加 密 的 。 


要 做 到 这 点 ， 你 需要 在 kibana.yml 里 配置 Elasticsearch 的 URL 时 指明 是 HTTPS 协 议 : 


elasticsearch: "https://«your elasticsearch host».com:9200" 


如 果 你 给 Elasticsearch 用 的 是 自己 签名 的 证 书 ， 请 在 kibana.yml 里 设 定 ca 参数 指明 PEM 文 件 位 置 ， 这 也 意味 着 开启 了 verify_ss| 参 数 : 


# If you need to provide a CA certificate for your Elasticsarech instance, put 
# the path of the pem file here. 
ca: /path/to/your/ca/cacert.pem 


18.2.4 控制 访问 权限 


你 可 以 用 Elasticsearch Shield 来 控制 用 户 通过 Kibana 可 以 访问 到 的 Elasticsearch 数 据 。Shield 提 供 了 索引 级 别 的 访问 控制 。 如 果 一 个 用 户 没 被 许可 运行 这 个 请 求 ， 那 么 它 在 Kibana 可 视 化 界面 上 只 能 看 


到 一 个 空白 。 


配置 Kibana 使 用 Shield， 你 要 位 Kibana 创 建 一 个 或 者 多 个 Shield 角 色 (role) ， 以 kibana 4 作为 开头 的 默认 角色 。 更 详细 的 做 法 ， 请 阅读 官方 Shield 产 品 文档 的 “Using Shield with Kibana 4” 小 


2i 


18.3 ”Discover 功 能 


Discover 标 签 页 用 于 交互 式 探索 你 的 数据 。 你 可 以 访问 到 匹配 得 上 你 选择 的 索引 模式 的 每 个 索引 的 每 条 记录 。 你 可 以 提交 搜索 请 求 ， 过 滤 搜 索 结 果 ， 然 后 查看 文档 数据 。 你 还 可 以 看 到 匹配 搜索 请 求 的 
文档 总 数 ， 获 取 字 段 值 的 统计 情况 。 如 果 索 引 模 式 配 置 了 时 间 字 段 ， 文 档 的 时 序 分 布 情况 会 在 页 面 顶部 以 柱状 图 的 形式 展示 出 来 。Discover 页 面 布 局 如 图 18-5 所 示 。 
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图 18-5 Discover X dip Ej 


时 间 过 滤器 (Time Filter) 限制 搜索 结果 在 一 个 特定 的 时 间 周 期 内 。 如 果 你 的 索引 包含 的 是 时 序 诗句 ， 而 且 你 为 所 选 的 索引 模式 配置 了 时 间 字段 ， 那 么 就 就 可 以 设置 时 间 过 滤器 。 


默认 的 时 间 过 滤器 设置 为 最 近 15 分 钟 。 


时 间 选 择 器 来 修改 时 间 过 滤器 : 


Ww 


ul 


你 可 以 用 页 面 项 部 的 时 间 选 择 器 (Time Picker) 来 修改 时 间 过 滤器 ， 或 者 选择 一 个 特定 的 时 间 间 隔 ， 或 者 直方 图 的 时 间 范围 。 


1) 点 击 菜单 栏 右 上 角 显 示 的 Time Filter 打 开 时 间 选 择 器 。 
2) 快速 过 滤 ， 直 接 选择 一 个 短 链接 即 可 。 


要 指定 相对 时 间 过 滤 ， 点 击 Relative 然 后 输入 一 个 相对 的 开始 时 间 。 可 以 是 任意 数字 的 秒 、 分 、 小 时 、 天 、 月 甚至 年 之 前 。 


4) 要 指定 绝对 时 间 过 滤 ， 点 击 Absolute 然 后 在 From 框 内 输入 开始 日 期 ，To 框 内 输入 结束 日 期 。 


点 击 时 间 选 择 器 底部 的 箭头 隐藏 选择 器 。 


从 直方 图 上 设置 时 间 过 滤器 ， 有 以 下 几 种 方式 : 


“ 想 要 放大 那个 时 间 间 隔 ， 点 击 对 应 的 柱 体 。 


“ 单 击 并 拖 搜 一 个 时 间 区 域 。 注 意 需 要 


等 到 光标 变 成 加 号 ， 才 意味 着 这 是 一 个 有 效 的 起 始点 。 


你 可 以 用 浏览 器 的 后 退 键 来 回 退 你 的 操作 。 


18.3.2 ”搜索 数据 


在 Discover 页 提交 一 个 搜索 ， 你 就 可 以 搜索 匹配 当前 索引 模式 的 索引 数据 了 。 你 可 以 直接 输入 简单 的 请 求 字符 串 ， 也 就 是 用 Lucene query syntax， 也 可 以 用 完整 的 基于 JSON 的 Query DSL。 具 体 示 


例 ， 参 见 之 前 Elasticsearch 章 节 。 


当 你 提交 搜索 的 时 候 ， 直 方 图 ， 文 档 表格 ， 字 段 列 表 ， 都 会 自动 反映 成 搜索 的 结果 。hits (匹配 的 文档 ) 总 数 会 在 直方 图 的 右上 角 显 示 。 文 档 表格 显示 前 500 个 匹配 文档 。 默 认 的 ， 文 档 倒序 排列 ， 最 新 
的 文档 最 先 显示 。 你 可 以 通过 点 击 时 间 列 的 头 部 来 反 转 排序 。 事 实 上 ， 所 有 建 了 索引 的 字段 ， 都 可 以 用 来 排序 ， 稍 后 会 详细 说 明 。 


要 搜索 数据 ， 应 按 如 下 步骤 操作 : 


1) 在 搜索 框 内 输入 请 求 字符 串 : 


a) 简单 的 文本 搜索 ， 直 接 输 入 文本 字符 串 。 比 如 ， 如 果 你 在 搜索 网 站 服务 器 日 志 ， 你 可 以 输入 safari 来 搜索 各 字段 中 的 safari 单 词 。 


b) 要 搜索 特定 字段 中 的 值 ， 则 在 值 和 前 


0 上 字段 名 。 比 如 ， 你 可 以 输入 status: 200 来 限制 搜索 结果 都 是 在 status 字 段 里 有 200 内 容 。 


c) 要 搜索 一 个 值 的 范围 ， 你 可 以 用 范围 查询 语法 ，[START_VALUE TO END_VALUE]。 比 如 ， 要 查找 4xx 的 状态 码 ， 你 可 以 输入 status: [400 TO 499]。 


d) 要 指定 更 复杂 的 搜索 标准 ， 你 可 以 F 


extension: html) 。 


布尔 操作 符 AND，OR， 和 NOT。 比 如 ， 要 查找 4xx 的 状态 码 ， 还 是 php 或 html 结 尾 的 数据 ， 你 可 以 输入 status: [400 TO 499]AND (extension: php OR 


2) 点 击 回 车 键 ,或 者 点 击 Search 按 钮 提交 你 的 搜索 请 求 。 


1 开始 一 个 新 的 搜索 


清除 当前 搜索 或 开始 一 个 新 搜索 ， 点 击 Discover 工 具 栏 的 New Search 按 钮 。 如 图 18-6 所 示 。 


ee — ~— CIT 


2. 保 存 搜索 


你 可 以 在 Discover 页 加 载 已 保存 的 搜索 ， 也 可 以 


要 保存 当前 搜索 : 


1) 点 击 Discover 工 具 栏 的 Save Sea rch 按 乌 国 ， 


2) 输入 一 个 名 称 ， 点 击 Save。 


3. 加 载 一 个 已 存 搜索 


要 加 载 一 个 已 保存 的 搜索 ， 如 下 所 示 : 


1) 点 击 Discover 工 具 栏 的 Load Searches, 


2) 选择 你 要 加 载 的 搜索 。 


如 果 已 保存 的 搜索 关 


4 改变 你 搜索 的 索引 


当 你 提交 一 个 搜索 请 求 ， 


要 选择 另外 的 索引 模式 : 


1) 点 击 Discover 工 具 栏 的 Settings 按 钮 。 


N 


5j 


亦 可 以 配置 一 个 刷新 间隔 来 


关于 索引 模式 的 更 多 细节 ， 请 阅读 稍 


从 索引 模式 列表 中 选取 你 打算 采用 的 模式 。 


自动 刷新 页 夯 


要 设置 刷新 闻 隔 ， 应 如 下 操作 : 


1) 点 击 菜 和 


2) 点 击 Refresh Interval 标 签 。 


3) 从 列表 中 选择 一 个 刷新 闻 隔 。 


BEA EfüligTime rite [9], 


后 Setting 功 能 小 节 。 


图 18-6 ”新 搜索 按钮 


要 想 自动 刷新 数据 ， 点 击 (时 CEE 各 Auto_refresh 按 钮 然后 选择 一 个 自动 刷新 间隔 。 


开启 


自动 刷新 后 ，Kibana 的 顶部 栏 会 出 现 一 个 暂停 按钮 和 自 


18.3.3” 按 字段 过 滤 


殿 到 跟 你 当前 选择 的 索引 模式 不 一 样 的 其 他 索引 上 ， 加 载 这 个 搜索 也 会 切换 当前 的 已 选 索 引 模式 。 


作 visualizations 的 基础 。 保 存 一 个 搜索 ， 意 味 着 同时 保存 下 了 搜索 请 求 字符 串 和 当前 选择 的 索引 模式 。 


匹配 当前 的 已 选 索引 模式 的 索引 都 会 被 搜索 。 当 前 模式 会 显示 在 搜索 栏 下方 。 要 改变 搜索 的 索引 ， 需 要 选择 另外 的 模式 。 


自动 刷新 Discover 页 面 的 最 新 索引 数据 。 这 回 定期 重新 提交 一 次 搜索 请 求 。 设 置 刷新 闻 隔 后 ， 


显示 在 菜单 栏 时 间 过 滤器 的 左边 。 


动 刷新 的 间隔 ; [有 本， 上 击 pause 按 钮 可 以 暂停 自动 刷新 。 


你 可 以 过 滤 搜 索 结 果 ， 只 显示 在 某 字段 中 包含 了 特定 值 的 文档 。 也 可 以 创建 反 向 过 滤器 ， 排 除 掉包 含 特定 字段 值 的 文档 。 


你 可 以 从 字段 列表 或 者 文档 表格 里 添加 过 滤器 。 当 你 添加 好 一 个 过 滤器 后 ， 它 会 显示 在 搜索 请 求 下 方 的 过 滤 栏 号 
注意 ， 当 该 字段 类 型 有 冲突 的 时 候 ， 则 无 法 创建 过 滤 。 


然 ) , 


切换 过 滤器 开关 ， 或 者 完全 移 除 掉 它 。 


要 从 字段 列表 添加 过 滤器 ， 应 如 下 操作 : 


= 


Ww 


1 


Ww 


点 击 你 想 要 过 滤 的 字段 名 。 会 显示 这 个 字段 的 前 5 名 数据 。 每 个 数据 的 右 人 出， 有 两 个 小 按钮 : 一 个 


2) 要 添加 正 向 过 滤器 ， 点 击 Positive Filter 按 钮 ， 这 会 过 滤 掉 在 本 字段 不 包含 这 个 数据 的 文档 。 


要 添加 反 向 过 滤器 ， 点 击 Negative Filter 按 钮 ， 这 会 过 滤 掉 在 本 字段 包含 这 个 数据 的 文档 。 


点 击 表格 第 一 列 (通常 都 是 时 间 ) 文档 内 容 左 侧 的 Expand 按 钮 


要 从 文档 表格 添加 过 滤器 ， 应 如 下 操作 : 


2) 要 添加 正 向 过 滤器 ， 点 击 Positive Filter 按 钮 ， 这 会 过 滤 掉 在 本 字段 不 包含 这 个 数据 的 文档 。 


要 添加 反 向 过 滤器 ， 点 击 Negative Filter 按 钮 ， 这 会 过 滤 掉 在 本 字段 包含 这 个 数据 的 文档 。 


18.3.4 ”过 滤器 的 协同 工作 方式 


在 Kibana 的 任意 页 面 创建 过 滤器 后 ， 就 会 在 搜索 输入 框 的 下 方 出 现 一 个 绿色 椭圆 形 的 过 滤 条 件 ， 如 


鼠标 移动 到 过 滤 条 件 上 ， 会 显示 几 个 医 


标 ， 如 


18-8 所 示 。 


. 从 过 滤 栏 上 


e» 


你 可 以 编辑 或 者 关闭 一 个 过 滤器 ， 转 换 过 滤器 (从 正 向 改 成 


18-7 所 示 。 


展开 文档 表格 中 的 文档 。 每 个 字段 名 的 右 人 出 ， 有 两 个 小 按钮 : 一 个 用 来 添加 常规 ( 正 向 ) 过 滤器 ， 一 个 


来 添加 常规 ( 正 向 ) 过 滤器 ， 一 个 用 来 添加 反 向 过 滤器 。 


zh 


来 添加 反 向 过 滤器 。 


反之 亦 


play. name: "Two Gentlemen of Verona" Essi 


图 18-7 过 滤器 示例 


518-8 ”过 滤器 操作 图 标 


Misz 关 。 点 击 这 个 图 标 ， 可 以 在 不 移 除 过 滤器 的 情况 下 关闭 过 滤 条 件 。 再 次 点 击 则 重新 打开 。 被 禁用 的 过 滤器 是 条 纹 状 的 灰色 ， 要 求 包含 (相当 于 Kibana 3 里 的 must) 的 过 滤 条 件 显 示 为 绿 
色 ， 要 求 排除 (相当 于 Kibana 3 里 的 mustNot) 的 过 滤 条 件 显示 为 红色 。 


Elese. 点 击 这 个 图 标 可 “ 钉 住 ”过 滤器 。 被 钉 住 的 过 滤器 ， 可 以 横贯 Kibana 各 个 标签 生效 。 比 如 在 Visualize 标 签 页 钉 住 一 个 过 滤器 ， 然 后 切换 到 Discover 或 者 Dashboard 标 签 页 ， 过 滤器 依 
然 还 在 。 注 意 ， 如 果 你 钉 住 了 过 滤器 ， 然 后 发 现 检索 结果 为 空 ， 注 意 查看 当前 标签 页 的 索引 模式 是 不 是 跟 过 滤器 匹配 。 


[id 涉 器 反 转 。 点 击 这 个 图 标 可 “ 反 转 " 过 泪 器 。 默认 情况 下 ， 过 滤器 都 是 包含 型 ， 显 示 为 绿色 ， 只 有 匹配 过 滤 条 件 的 结果 才 会 显示 。 反 转 成 排除 型 过 滤器 后 ， 显 示 的 是 不 匹配 过 滤器 的 检索 项 ， 显 示 
为 红色 。 


回 移 除 过 滤器 。 点 击 这 个 图 标 将 删除 过 滤器 。 


想 要 对 当前 页 所 有 过 滤器 统一 执行 上 面 的 某 个 操作 ， 点 击 生 GtiOnSs P Global Filter Actions 按 钮 ， 然 后 再 执行 操作 即 可 。 


18.35 ”查看 文档 数据 


当 你 提交 一 个 搜索 请 求 ， 最 近 的 500 个 搜索 结果 会 显示 在 文档 表格 里 。 你 可 以 在 Advanced Settings 里 通过 discover: sampleSize 属 性 配置 表格 里 具体 的 文档 数量 。 默 认 情 况 下 ， 表 格 会 显示 当前 选择 的 
索引 模式 中 定义 的 时 间 字 段 内 容 (转换 成 本 地 时 区 ) 以 及 _source 文 档 。 你 可 以 从 字段 列表 添加 字段 到 文档 表格 。 还 可 以 用 表格 里 包含 的 任意 已 建 索引 的 字段 来 排序 列 出 的 文档 。 


要 查看 一 个 文档 的 字段 数据 ， 点 击 表格 第 一 列 (通常 都 是 时 间 ) LERRAM Expandi, Kibana 从 Elasticsearch 读 取 数据 然后 在 表格 中 显示 文档 字段 。 如 图 18-9 所 示 。 这 个 表格 每 行 是 一 个 字 
段 的 名 字 、 过 滤器 按钮 和 字段 的 值 。 


Table JSON 


t emessage 175.119.129.130 - - [2015-05-29T20:41:19.3907] "GET /uploads/liu-wang.jpg HTT 
P/1.1" 200 4432 "-" "Mozilla/5.0 (X11; Linux 1686) AppleWebKit/534.24 (KHTML, 1 
ike Gecko) Chrome/11.0.696.50 Safari/534.24" 


t etags Q Q (I success, security 

© timestamp Q A (I May 20th 2015, 13:41:19.390 
-id & Q (I AUiu0kiJst9lcKRCDZK. 
-index & am logstash-2015.05.20 


-type @ am apache 


agent @ Q (I) Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/1 
1.0.696.50 Safari/534.24 


# bytes $ Q ID 4,432 
A clientip Q&Q Q mD 175.119.129.130 
t extension QQam jpg 


Q geo. coordinates &eamií 
"lat": 48.79275, 
"lon": -122.5375278 


18-9 展开 的 日 志 表 格 


查看 文档 的 方式 如 下 : 
“ 要 查看 原始 JSON 文 档 (格式 美化 过 的 ) ， 点 击 JSON 标 签 。 


“ 要 在 单独 的 页 面 上 查看 文档 内 容 ， 点 击 链接 。 你 可 以 添加 书签 或 者 分 享 这 个 链接 ， 以 直接 访问 这 条 特定 文档 。 


balh 


" 要 收回 文档 细节 ， 点 击 Collapse 按 多 


. A Drogen, 则 可 以 查看 文档 中 某 字 段 的 一 列 。 


1. 文 档 列表 排序 


你 可 以 用 任意 已 建 索引 的 字段 排序 文档 表格 中 的 数据 。 如 果 当 前 索引 模式 配置 了 时 间 字 段 ， 默 认 会 使 用 该 字段 倒序 排列 文档 。 


要 改变 排序 方式 ， 点 击 想 要 用 来 排序 的 字段 名 。 能 用 来 排序 的 字段 在 字段 名 右 侧 都 有 一 个 排序 按钮 。 再 次 点 击 字段 名 ， 就 会 反 向 排序 。 


2. 给 文档 表格 添加 字段 列 


默认 情况 下 ， 文 档 表格 会 显示 当前 选择 的 索引 模式 中 定义 的 时 间 字 段 内 容 (转换 成 本 地 时 区 ) 以 及 _source 文 档 。 你 可 以 从 字段 列表 添加 字段 到 文档 表格 。 
要 添加 字段 列 到 文档 表格 ， 应 如 下 操作 : 


1) 移动 鼠标 到 字段 列表 的 字段 上 ， 点 击 add 近 钮 E 了 


2) 重复 操作 直到 你 添加 完 所 有 你 想 移 除 的 字段 。 


添加 的 字段 会 蔡 换 掉 文 档 表格 里 的 source 列 ， 同 时 还 会 显示 在 字段 列表 项 部 的 Selected Fields 区 域 里 。 


要 重 排 表格 中 的 字段 列 ， 移 动 鼠 标 到 你 要 移动 的 列 顶 部 ， 点 击 移动 按钮 ， 如 图 18-10 所 示 。 


Time ^ index Gmessage ^ 
February 14th 2015, 10:36:51.075  logstash- EEI 5-02- 11r18:25:31. 0752 "GET /canhaz/yelena-kondak 
2015.02.14 ova.gif HTTP/1. 00 546 "-" "Mozilla/S.0 (X11; Linux 1686) 


pplewebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24" 


图 18-10 移动 表格 字段 的 方法 


3. 从 文档 表格 删除 字段 列 
要 从 文档 表格 删除 字段 列 ， 应 如 下 操作 : 


1) 移动 鼠标 到 字段 列表 的 Selected Fields 区 域 里 想 要 移 除 的 字段 上 ， 然 后 点 击 它 的 remove 近 钮 E 3 . 


2) 重复 操作 直到 你 移 除 完 所 有 想 移 除 的 字段 。 


4. 查 看 字段 数据 统计 


从 字段 列表 中 ， 你 可 以 看 到 文档 表格 里 有 多 少数 据 包含 了 这 个 字段 ， 排 名 前 5 的 值 是 什么 ， 以 及 包含 各 个 值 的 文档 的 占 比 ， 如 图 18-11 所 示 。 


t extension 


Quick Count ( 93 /93 records ) 
ipg | aa 


aa 


aqa 


aa 


基于 这 个 字段 创建 可 视 化 ， 点 击 字段 统计 下 方 的 Visualize 按 钮 。 


184 各 种 可 视 化 功能 


Visualize 标 签 页 用 来 设计 可 视 化 。 你 可 以 保存 可 视 化 结果 供 以 后 再 用 ， 或 者 加 载 合并 到 仪表 盘 里 。 可 视 化 功能 可 以 基于 以 下 几 种 数据 源 类 型 : 


“ 新 的 交互 式 搜索 。 
“ 已 保存 的 搜索 。 
“ 已 保存 的 可 视 化 。 


可 视 化 是 基于 Elasticsearch 1.0 引 入 的 聚合 (aggregation) 特性 。 


创建 可 视 化 可 开始 于 New Visualization 向 导 ， 点 击 页 面 左 上 角 的 Visualize 标 签 。 如 果 你 已 经 在 创建 一 个 可 视 化 了 ， 你 可 以 在 搜索 栏 的 右 侧 工具 栏 里 点 击 New Visualization 按 钮 加 向 导 会 引导 你 继续 
以 下 几 步 进行 创建 : 


1) 在 New Visualization 向 导 起 始 页 选择 可 视 化 类 型 ， 或 加 载 一 个 之 前 保存 的 可 视 化 。 


已 存 可 视 化 选择 器 包括 一 个 文本 框 用 来 过 滤 可 视 化 名 称 ， 以 及 一 个 指向 “对 象 编辑 器 ” (Object Editor) 的 链接 ， 可 以 通过 Settings 一 Edit Saved Objects 来 管理 已 存 的 可 视 化 。 


如 果 你 的 新 可 视 化 是 一 个 Markdown 挂 件 ， 选 择 这 个 类 型 会 带 你 到 一 个 文本 内 容 框 ， 你 可 以 在 框 内 输入 打算 显示 在 挂件 里 的 文本 。 其 他 的 可 视 化 类 型 ， 选 择 后 都 会 转 到 数据 源 选择 。 下 一 节 开 始 ， 会 详 
细 介 绍 各 种 可 视 化 类 型 的 操作 。 


2) 选择 数据 源 。 你 可 以 选择 新 建 或 者 读 取 一 个 已 保存 的 搜索 ， 作 为 可 视 化 的 数据 源 。 搜 索 是 和 一 个 或 者 一 系列 索引 相关 联 的 。 如 果 你 选择 了 在 一 个 配置 了 多 个 索引 的 系统 上 开始 你 的 新 搜索 ， 从 可 视 化 
编辑 器 的 下 拉 菜单 里 选择 一 个 索引 模式 。 


当 你 从 一 个 已 保存 的 搜索 开始 创建 并 保存 好 了 可 视 化 ， 这 个 搜索 就 绑 定 在 这 个 可 视 化 上 。 如 果 你 修改 了 搜索 ， 对 应 的 可 视 化 也 会 自动 更 新 。 


3) 操作 可 视 化 编辑 器 


可 视 化 编辑 器 用 来 配置 、 编 辑 可 视 化 ， 如 图 18-12 所 示 ， 有 下 面 几 个 主要 元 素 : 工具 栏 、 聚 合 构建 器 、 预 览 画 布 。 下 面 分 别 介绍 。 


图 18-12 可视化 编辑 器 布局 


1. 工 具 栏 (Toolbar) 


工具 栏 上 有 一 个 用 户 交互 式 数据 搜索 的 搜索 框 ， 用 来 保存 和 加 载 可 视 化 。 因 为 可 视 化 是 基于 保存 好 的 搜索 ， 搜 索 栏 会 变 成 灰色 。 要 编辑 搜索 ， 双 击 搜索 框 ， 用 编辑 后 的 版 本 替换 已 保存 搜索 。 


搜索 框 右 侧 的 工具 栏 有 一 系列 按钮 ， 用 于 创建 新 可 视 化 ， 保 存 当 前 可 视 化 ， 加 载 一 个 已 有 可 视 化 ,分享 或 内 赃 可 视 化 ， 刷 新 当前 可 视 化 的 数据 。 


2. 聚 合 构建 器 (Aggregation Builder) 


页 面 左 侧 的 聚合 构建 器 配置 你 的 可 视 化 要 用 的 metric 和 bucket 聚 合 。 桶 (Buckets) 的 效果 类 似 于 SQL GROUP BY 语句 。 想 更 详细 地 了 解 聚合 ， 请 阅读 Elasticsearch aggregations reference, 


在 柱状 图 或 者 折线 图 可 视 化 里 ， 用 metrics 做 Y 轴 ， 然 后 buckets 做 X 轴 ， 条 带 颜 色 ， 以 及 行 / 列 的 区 分 。 在 饼 图 里 ，metrics 用 来 做 分 片 的 大 小 ，buckets 做 分 片 的 数量 。 


为 你 的 可 视 化 Y 轴 选 一 个 metric 聚 合 ， 包 括 count、average、sum、min、max、cardinality (unique count) 。 为 你 的 可 视 化 X 轴 、 条 带 颜 色 、 行 / 列 的 区 分 选 一 个 bucket 聚 合 ， 常 见 的 有 date 


histogram、range、terms、filters 和 significant terms, 


网 


你 可 以 设置 buckets 执 行 的 顺序 。 在 Elasticsearch 里 ， 第 一 个 聚合 决定 了 后 续 聚 合 的 数据 集 。 下 面 的 例子 演示 一 个 网 页 访问 量 前 五 名 的 文件 后 缀 名 统计 的 时 间 柱 状 图 。 


看 所 有 相同 后 缀 名 的 ， 设 置 顺序 如 下 : 


1) Color: 后 缀 名 的 Terms 聚 合 。 


2) X-Axis: @timestamp 的 时 间 柱 状 


IR] 


R 


Elasticsearch 收 集 记 录 ， 算 出 前 5 名 后 缀 名 ， 然 后 为 每 个 后 缀 名 创建 一 个 时 间 柱 状 图 。 


要 看 每 个 小 时 的 前 5 名 后 级 名 情况 ， 设 置 顺序 如 下 : 


1) X-Axis: @timestamp 的 时 间 柱 状 图 (1 小 时 间隔 ) 。 


2) Color: 后 缀 名 的 Terms 聚 合 。 


这 次 ，Elasticsearch 会 从 所 有 记录 里 创建 一 个 时 间 柱 状 图 ， 然 后 在 每 个 桶 内 ,分 组 (本 例 中 就 是 一 个 小 时 的 间隔 ) 计算 出 前 5 名 的 后 缀 名 。 
记 住 ， 每 个 后 续 的 桶 ， 都 是 从 前 一 个 的 桶 里 分 割 数据 。 
要 在 “预览 画布 ” (preview canvas) 上 泻 染 可 视 化 ， 点 击 聚合 构建 器 底部 的 Apply 按 钮 。 


3. 预 览 画布 (Preview Canvas) 


预览 canvas 上 显示 你 定义 在 聚合 构建 器 里 的 可 视 化 的 预览 效果 。 要 刷新 可 视 化 预览 ， 点 击 工具 栏 里 的 Refresh 技 钮 回 . 


下 面 几 个 小 节 就 分 别 介绍 各 种 可 视 化 的 功能 。 
18.4.1 area 


这 种 图 的 Y 轴 是 “数值 ”维度 。 该 维度 有 很 多 聚合 可 用 ， 参 见 表 18-1。 


表 18-1 area 图 Y 轴 的 聚合 
聚合 名 称 说 —H 
count 聚合 接口 文档 见 http://Wwww.elastic co/guide/en/elasticsearch/reference/current//search-aggregations- 


— metrics-valuecount-aggregation html。 返 回 选中 索引 模式 中 元 素 的 原始 计数 

— avg 聚合 接口 文 档 见 http://www.elastic col TREE 
metrics-avg-aggregation html。 返 回 一 个 数值 字段 平均 值 ， 从 下 拉 药 单 选择 一 个 字段 

T" sum 聚合 接口 文档 见 http://www elastic.co/guide/en/elasticsearch/reference/current//search-aggregations- 
metrics-sum-aggregation html。 返 回 一 个 数值 字段 的 总 和 ， 从 下 拉 菜 单 选 择 一 个 字段 

"- min Aik O 3C P4 UL httpz/www.elastic.co/guide/en/elasticsearch/reference/current//search-aggregations- 
metrics-min-aggregation.html。 返 回 一 个 数值 字段 的 最 小 值 ， 从 下 拉 菜 单 选择 一 个 字段 

max 陛 合 接口 文档 见 http;//www elastic co/guide/en/elasticsearch/reference/current//search-aggregations- 


metrics-max-aggregation.html。 返 回 一 个 数值 字段 的 最 大 值 ， 从 下 拉 莱 单 选择 一 个 字段 
cardinality 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current//search- 
Unique Count aggregations-metrics-cardinality-aggregation html。 返 回 一 个 字段 的 去 重 数据 值 ， 从 下 拉 某 单 选 
择 一 个 字段 
percentile 聚合 接口 文档 见 http-//www.elastic.co/guide/en/elasticsearch/reference/current//search- 
aggregations-metrics-percentile-aggregation.html。 返 回 一 个 数值 字段 中 值 的 百分比 分 布 。 从 下 


Portae 拉 菜 单 选择 一 个 字段 ， 然 后 在 Percentiles 框 内 指定 范围 。 点 击 X 移 除 一 个 百分比 框 ， 点 击 
+Add 添加 一 个 百分比 框 
percentile ranks 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current// 
search-aggregations-metrics-percentile-rank-aggregation.html。 返 回 一 个 数值 字段 中 你 指定 值 的 
Percentile Rank 


百 分 位 排名 。 从 下 拉 菜 单 选择 一 个 字段 ， 然 后 在 Values 框 内 指定 一 到 多 个 百 分 位 排名 值 。 点 
击 义 移 除 一 个 百分比 框 ， 点击 +Add 添加 一 个 数值 框 


你 可 以 点 击 +Add Aggregation 按 钮 添加 一 个 聚合 。buckets 聚 合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 图 形 的 X 轴 是 buckets 维 度 。 你 可 以 为 X 轴 定义 buckets， 同 样 还 可 以 为 图 片上 的 分 片区 域 ， 或 
者 分 割 的 图 片 定义 buckets。 


该 图 形 的 X 轴 支持 很 多 聚合 ， 如 表 18-2 所 示 。 点 击 每 个 聚合 的 链接 查看 该 聚合 的 Elasticsearch 官 方 文档 。 


表 18-2 atea 图 又 轴 的 聚合 


聚合 名 称 说 RA 
date histogram 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current// 
Date Histogram search-aggregations-bucket-datehistogram-aggregation html。 基 于 数值 字段 创建 ， 由 时 间 组 织 
起 来 。 你 可 以 指定 时 间 片 的 间隔 。 单 位 包括 秒 、 分 、 小 时 、 天 、 星 期 、 月 、 年 
histogram 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current//search- 
Histogram aggregations-bucket-histogram-aggregation html。 基 于 数值 字段 创建 ， 为 这 个 字段 指定 一 个 整 
数 间隔 。 匀 选 Show empty buckets 让 直方 图 中 包含 空 的 间隔 
range 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current//search- 
Range aggregations-bucket-range-aggregation htm1。 可 以 为 一 个 数值 字段 指定 一 系列 区 间 ， 点 击 Add 
Range 添加 一 对 区 间 端 点 。 点 击 红色 (x) 符号 移 除 一 个 区 间 


(AX ) 


聚合 名 称 说 了 表 
date range 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current//search- 
aggregations-bucket-daterange-aggregation.html。 计 算 你 指定 的 时 间 区 间 内 的 值 。 可 以 使 用 


“ss date math 表达 式 指定 区 间 ， 点 击 Add Range 添加 新 的 区 间 端 点 ,点击 红色 CO 符号 移 除 
区 间 

ip range 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current//search- 

IPv4 Range aggregations-bucket-iprange-aggregation.html。 用 来 指定 IPv4 地 址 的 区 间 ， 点 击 Add Range 


添加 新 的 区 间 端 点 ， 点 击 红色 (/) 符号 移 除 区 间 
terms 聚合 接口 文档 见 http:/www.elastic.co/guide/en/elasticsearch/reference/current//search- 

Terms aggregations-bucket-terms-aggregation.html。 人 允许 你 指定 展示 一 个 字段 的 首尾 几 个 元 素 ， HET 
方式 可 以 是 计数 或 者 其 他 自 定义 的 metric 

filters 聚合 接口 文档 见 http-//www.elastic.co/guide/en/elasticsearch/reference/current//search- 
aggregations-bucket-filters-aggregation.html。 你 可 以 为 数据 指定 一 组 filters， 每 个 filters 中 
可 以 用 query string， 也 可 以 用 JSON 格式 ， 就 像 在 Discover 页 的 搜索 栏 里 一 样 。 点 击 Add 
Filter 添加 下 一 个 过 滤器 

significant terms 聚合 接口 文档 见 http://www.elastic.co/guide/en/elasticsearch/reference/current// 
search-aggregations-bucket-significantterms-aggregation html. Jg significant terms 的 结果 


Filters 


Significant Terms 


一 旦 你 定义 好 了 一 个 X 轴 聚合 。 你 可 以 继续 定义 子 聚合 来 完善 可 视 化 效果 。 点 击 +Add Sub Aggregation 添 加 子 聚 合 ， 然 后 选择 Split Area 或 者 Split Chart， 并 从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 优先 级 。 比 如 ， 一 个 事件 计数 的 日 期 图 ， 可 以 按照 时 序 显示 ， 你 也 可 以 提升 事件 聚合 的 优先 级 ， 首 先 显示 最 活跃 的 几 
天 。 时 序 图 用 来 显示 事件 随 着 时 间 变 化 的 趋势 ， 而 按照 活跃 时 间 排序 则 可 以 揭示 你 数据 中 的 部 分 异常 值 。 


可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚 合 的 自 定义 参数 : 
“ Exclude Pattern: 指定 一 个 从 结果 集中 排除 掉 的 模式 。 
- Exclude Pattern Flags: 排除 模式 的 Java flags 标 准 集 。 
“ Include Pattern: 指定 一 个 从 结果 集中 要 包含 的 模式 。 
“ Include Pattern Flags: 包含 模式 的 Java flags 标 准 集 。 


“JSON Input: 一 个 用 来 添加 JSON 格 式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定义 中 ， 格 式 如 下 例 : 


{ “script : “doc['grade'].value * 1.2" } 


Oze 
Elasticsearch 1.4.3 及 以 后 版 本 ， 这 个 函数 需要 你 开启 dynamic Groovy scriptinge 
下 面 参数 是 否 可 用 ， 取 决 于 你 选择 的 聚合 函数 。 
选择 view options 更 改 表格 中 如 下 方面 : 
:Chart Mode: 当 你 为 图 形 定义 了 多 个 Y 轴 时 ， 你 可 以 用 该 下 拉 菜 单 定义 聚合 如 何 显示 在 图 形 上 : 
' Stacked: 聚合 结果 依次 登 加 在 顶部 。 


Overlap: 聚合 结果 重 登 的 地 方 采用 半 透 明 效 果 。 


: Wiggle: 聚合 结果 显示 成 streamgraph 效 果 。 
` Percentage: 显示 每 个 聚合 在 总 数 中 的 百 分 值 。 


* Silhouette: 显示 每 个 聚合 距离 中 间 线 的 方差 。 


多 选 框 可 以 用 来 控制 以 下 行为 : 


“ Smooth Lines: 勾 选 该 项 平滑 数据 点 之 间 的 折线 成 曲线 。 

* Set Y-Axis Extents: 勾 选 该 项 ， 然 后 在 y-max 和 y-min 框 里 输入 数值 限定 Y 轴 为 指定 数值 。 

“Scale Y-Axis to Data Bounds: 默认 的 Y 轴 长 度 为 0 到 数据 集 的 最 大 值 。 勾 选 该 项 改变 Y 轴 的 最 大 和 最 小 值 为 数据 集 的 返回 值 。 
. Show Tooltip: 4 ub ERE T RU. 


* Show Legend: 勾 选 该 项 在 图 形 右 侧 显 示 图 例 。 


18.4.2 table 


. Average, Sum, Min, Max, Unique Coun, Percentile, Percentile Rank。 大 部 分 聚合 的 说 明 在 18.4.1 节 “area” 已 经 提供 ， 还 有 一 个 不 太一 样 


这 种 图 的 数值 可 以 采用 以 下 metric 聚 合 : Count 
的 聚合 是 Standard Deviation: extended stats 聚 合 (http://www.elastic.co/guide/en/elasticsearch/reference/current//search-aggregations-metrics-extendedstats-aggregation.html) 返回 一 个 


数值 字段 数据 的 标准 差 。 从 下 拉 菜 单 选择 一 个 字段 。 


你 可 以 点 击 +Add Aggregation 按 键 添加 一 个 聚合 。 数 据 表格 的 每 行 ， 叫 做 buckets。 你 可 以 定义 puckets 来 切割 表格 成 行 ， 或 者 切割 表格 成 另 一 个 表格 。 


每 个 bucket 类 型 都 支持 以 下 聚合 : Date Histogram, Histogram, Range, Date Range, IPv4 Range, Terms, Filters, Significant Terms， 同 样 ， 大 部 分 聚合 已 在 18.4.1 节 “area” 中 说 明 ， 还 有 


一 个 不 太一 样 的 聚合 是 Geohash: geohash 聚 合 (http://www.elastic.co/guide/en/elasticsearch/reference/current//search-aggregations-bucket-geohashgrid-aggregation.html) 显示 基于 地 理 


一 旦 你 定义 好 了 一 个 X 轴 聚合 ， 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 +Add Sub Aggregation 添 加 子 聚 合 ， 然 后 选择 Split Area 或 者 Split Chart， 并 从 类 型 菜单 中 选择 一 个 子 聚 合 。 


聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 优先 级 。 你 可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚合 的 自 定义 参数 ， 这 部 分 参见 18.4.1 节 “area”。 


当 一 个 


形 中 定义 了 多 个 聚合 ， 你 可 以 使 
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下 面 参数 是 否 可 用 ， 取 决 于 你 选择 的 聚合 函数 。 选 择 view options 更 改 表格 中 如 下 方面 : 


“ Per Page: 这 个 输入 框 控 制 表格 的 翻 页 。 默 认 值 是 每 页 10 行 。 


多 选 框 用 来 控制 以 下 行为 : 


* Show metrics for every bucket/level: 勾 选 此 项 用 以 显示 每 个 bucket 聚 合 的 中 间 结 果 。 


“ Show partial rows: 勾 选 此 项 显示 没有 数据 的 行 。 


Qus 


开启 这 些 行为 可 能 带 来 性 能 上 的 显著 影响 。 


18.4.3 line 


这 种 图 的 Y 轴 是 “数值 ”维度 。 该 维度 可 用 聚合 参见 18.4.2 节 “table”。 


你 可 以 点 击 +Add Aggregation 按 键 添加 一 个 聚合 。 


buckets 聚 合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 


图 切 分 必须 在 其 他 聚合 之 前 要 运行 。 如 果 你 切 分 图 形 ， 你 可 以 选择 切 分 结果 是 展示 成 行 还 是 列 的 形式 ， 点 
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在 你 选 定 一 个 buckets 聚 合 之 前 ， 先 指定 你 是 要 切割 单个 图 的 分 片 ， 还 是 切割 成 多 个 图 
击 Rows|Columns 选 择 器 即 可 。 


轨 形 的 X 轴 是 buckets 维 度 。 你 可 以 为 X 轴 定义 buckets， 同 样 还 可 以 为 图 片上 的 分 片区 域 ， 或 者 分 割 的 图 片 定义 buckets。 


该 图 形 的 X 轴 支持 的 聚合 参见 18.4.1 节 中 的 表 18-2。 


后 选择 Split Area 或 者 Split Chart， 并 从 类 型 菜单 中 选择 一 个 子 聚合 。 


一 旦 你 定义 好 了 一 个 X 轴 聚合 ， 可 以 继续 定义 子 聚合 来 完善 可 视 化 效果 。 点 击 +Add Sub Aggregation 添 加 子 聚合 ， 然 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 优先 级 。 


可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚 合 的 自 定义 参数 ， 这 部 分 和 18.4.1 节 “area” 一 致 。 


下 面 参数 是 否 可 用 ， 取 决 于 你 选择 的 聚合 函数 。 


多 选 框 可 以 用 来 控制 以 下 行为 : 


图 表 ; 也 可 以 用 平方 根 (square root) 比例 显示 数值 变化 差异 极 大 的 数 


- Y-Axis Scale: 可 以 给 图 形 的 Y 轴 选择 linear、log 或 square root 三 种 比例 。 你 可 以 给 指数 变化 的 数据 采用 log 函 数 比例 显示 ， 比 如 复 利 
性 本 身 也 算 交 量 的 一 种 的 数据 ， 又 叫 异 方差 数据 。 比 如 ， 身 高 和 体重 的 数据 集 ， 在 较 矮 的 区 间 变 化 是 很 小 的 ， 但 是 在 较 高 另 一 个 区 间 ， 数 据 集 就 是 异 方差 式 的 。 


Hiko RATX! 


: Smooth Lines: 勾 选 该 项 ， 将 图 中 的 数据 点 用 平滑 曲线 连接 。 注 意 : 平滑 曲线 在 高 峰 低 谷 处 给 人 的 印象 与 实际 值 有 较 大 偏差 
' Show Connecting Lines: 勾 选 该 项 ， 将 图 中 的 数据 点 用 折线 连接 。 


* Show Circles: 义 选 该 项 ， 将 图 中 的 数据 点 绘制 成 一 个 小 圆圈 。 


* Current time marker: 对 时 序数 据 ， 义 选 该 项 可 以 在 当前 时 刻 位 置 标记 一 条 红线 。 

* Set Y-Axis Extents: 勾 选 该 项 ， 然 后 在 y-max 和 y-min 框 里 输入 数值 限定 Y 轴 为 指定 数值 。 
. Show Tooltip: 为 选 该 项 显示 工具 栏 。 

. Show Legend: 勾 选 该 项 在 图 形 右 侧 显 示 图 例 。 


* Scale Y-Axis to Data Bounds: 默认 的 Y 轴 长 度 为 0 到 数据 集 的 最 大 值 。 匀 选 该 项 改变 Y 轴 的 最 大 和 最 小 值 为 数据 集 的 返回 值 。 


更 新 选项 后 ， 点 击 绿色 Apply changes 按 钮 更 新 可 视 化 界面 ， 或 者 灰色 Discard changes 按 钮 保持 原状 。 


通过 以 下 步骤 ， 可 以 转换 折线 
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成 气泡 | 
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1) 为 Y 轴 点 击 Add Metrics 然 后 选择 Dot Size, 
2) 从 下 拉 框 里 选择 一 个 metric 聚 合 函 数 。 


3) 在 Options 标 签 里 ， 去 掉 Show Connecting Lines 的 勾 选 。 


4) 点 击 Apply changes 按 钮 。 


18.4.4 Markdown 


Markdown 挂 件 是 一 个 存放 GitHub 风 格 Markdown 内 容 的 文本 框 。Kibana 会 泻 染 你 输入 的 文本 ， 然 后 在 仪表 盘 上 显示 泻 染 结果 。 可 以 点 击 Help 连 接 跳 转 到 help page 查 看 GitHub 风 格 Markdown 的 说 


明 。 点 击 Apply 在 预览 框 查看 渲染 效果 ， 或 者 Discard 回 退 成 上 一 个 版 本 的 内 容 。 


18.4.5 metric 


这 种 图 为 你 选择 的 聚合 显示 一 个 单独 的 数字 ， 可 用 聚合 参见 18.4.2 节 “table”。 


你 可 以 点 击 +Add Aggregation 按 键 添加 一 个 聚合 。 你 可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚 合 的 自 定义 参数 : 


.JSON Input: 一 个 用 来 添加 JSON 格 式 属性 的 文本 框 ， 内 容 会 合并 进 聚 合 的 定义 中 ， 格 式 如 下 例 : 


{ “script : “doc['grade'].value * 1.2" } 


Oza 
Elasticsearch 1.4.34 UEMA, 3X Ae i i E -ARI È dynamic Groovy sctiptings 


点 击 view options 修 改 显 示 metric 的 字体 大 小 。 


184.6 pie 


饼 图 的 分 片 大 小 通过 metrics 聚 合 定义 。 这 个 维度 可 以 支持 以 下 聚合 : Count, Sum, Unique Count, 


buckets 聚 合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 在 你 选 定 一 个 buckets 聚 合 之 前 ， 先 指定 你 是 要 切割 单个 图 的 分 片 ， 还 是 切割 成 多 个 图 形 。 多 


形 ， 你 可 以 选择 切 分 结果 是 展示 成 行 还 是 列 的 形式 ， 点 击 Rows|Columns 选 择 器 即 可 。 


网 


切 分 必须 在 其 他 聚合 之 前 要 运行 。 如 果 你 切 分 


网 


你 可 以 为 饼 图 指定 以 下 任意 bucket 聚 合 : Date Histogram, Histogram, Range, Date Range, IPv4 Range, Terms, Filters, Significant Terms， 这 些 与 18.4.1 节 “area” 一 致 。 


一 旦 你 定义 好 了 一 个 X 轴 聚合 ， 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 +Add Sub Aggregation 添 加 子 聚 合 ， 然 后 选择 Split Area 或 者 Split Chart， 并 从 类 型 菜单 中 选择 一 个 子 聚 合 。 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 你 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 优先 级 。 


可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚 合 的 自 定义 参数 ， 这 部 分 和 18.4.1 节 “area” 一 致 。 
下 


面 参 数 是 否 可 用 ， 取 决 于 你 选择 的 聚合 函数 。 


选择 view options 可 更 改 表格 中 如 下 方面 : 


: Donut: 用 甜 圈 代 替 饼 图 样式 。 


* Show Tooltip: 勾 选 该 项 显示 工具 栏 。 


“ Show Legend: 勾 选 该 项 在 图 形 右 侧 显示 图 例 。 


18.4.7 tile map 


瓦 片 地 图 显示 一 个 由 圆圈 覆盖 着 的 地 理 区 域 ， 这 些 圆圈 则 由 你 指定 的 buckets 控 制 。 


瓦 片 地 图 的 默认 metrics 聚 合 是 Count 聚 合 ， 你 还 可 以 选择 下 列 任意 聚合 : Count、Average、Sum、Min、Max、Unique Count, 


体 细节 参阅 18.4.1 节 “area”。 


buckets 聚 合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 在 你 选择 buckets 聚 合 前 ， 先 指定 你 是 打算 分 割 图 形 ， 还 是 在 单个 图 形 上 显示 buckets 为 Geo Coordinates。 多 图 切割 的 聚合 必须 在 最 先 运行 。 


瓦 片 地 图 使 用 Geohash 聚 合作 为 初始 化 聚合 。 从 下 拉 菜 单 中 选择 一 个 坐标 字段 ，Precision 滑 动 条 设置 圆圈 在 地 图 上 显示 的 颗粒 度 大 小 ， 可 阅读 geohash grid 聚 合 
(http://www.elastic.co/guide/en/elasticsearch/reference/current//search-aggregations-bucket-geohashgrid-aggregation.html# cell dimensions at the equator) 的 文档 ， 了 解 每 个 精度 级 别 


的 区 域 细节 。Kibana 4.1 目 前 支持 的 最 大 geohash 长 度 为 7。 


o 
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更 高 的 精度 意味 着 消耗 浏览 器 和 Elasticseartch 集 群 更 多 的 内 存 。 


一 旦 你 定义 好 了 一 个 X 轴 聚合 ， 可 以 继续 定义 子 聚合 来 完善 可 视 化 效果 。 点 击 +Add Sub Aggregation 添 加 子 聚 合 ， 然 


合 说 明 与 18.4.2 节 “table” 一致 。 


你 可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚 合 的 自 定义 参数 ， 这 部 分 和 18.4.1 节 “area” 一 致 。 


下 面 参数 是 否 可 用 ， 取 决 于 你 选择 的 聚合 函数 。 


< Map type: 从 下 拉 框 选择 下 面 一 个 选项 。 


选择 Options 改 变 可 视 化 的 如 下 方面 : 


* Shaded Circle Markers: 根据 mettic 聚 合 的 值 显 示 不 同 的 颜色 。 


* Scaled Circle Markers: 根据 metric 聚 合 的 值 显 


示 不 同 的 大 小 。 


“ Shaded Geohash Grid: 用 拢 形 替换 默认 的 圆 形 显示 geohash， 根 据 mettic 聚 合 的 值 显示 不 同 的 颜色 。 


: Heatmap:. 热力 图 可 以 


Radius: 设置 单个 热力 图 点 的 大 小 。 


Blur: 设置 热力 图 点 的 模糊 度 。 


异 糊 化 圆 标 而 且 层 登 显示 颜色 。 热 力图 本 身 还 有 如 下 选项 可 用 : 


- Maximum zoom: Kibana 的 Tilemap 支 持 18 级 缩放 。 该 选项 设置 热力 图 最 大 强度 下 的 最 高 缩放 级 别 。 


* Minimum opacity: 设置 数据 点 的 不 透明 截止 位 置 。 


“ Show Tooltip: 勾 选 该 项 ， 让 鼠标 放 在 数据 点 上 时 显示 该 点 的 数据 。 


“De 


更 新 选项 


saturate map tiles: 淡化 地 图 颜色 ， 凸 显 标记 


可 视 化 地 图 就 绪 后 ， 你 可 以 通过 以 下 方式 探索 地 


“在 地 


- 点 击 Zoom In/Out- 按钮 手动 修改 缩放 级 别 。 


的 清晰 度 。 


后 ， 点 击 绿色 Apply changes 按 钮 更 新 可 视 化 界面 ， 或 者 灰色 Discard changes 按 钮 保持 原状 。 
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- 点 击 Fit Data Bounds 4s iEJ6 A E 22 36 465] E Jp AAE ELR o 


“点击 Latitude/Longitude Filter Tlieta, 然后 在 地 图 上 拖 搜 绘制 一 个 方 框 ， 自 动 生成 这 个 框 范 围 的 经 纬度 过 滤器 。 


18.4.8 


vertical bar 


这 种 


到 的 Y 轴 是 “数值 ”维度 。 该 维度 的 可 用 聚合 与 18.4.2 节 “table” 一 致 。 


你 可 以 点 击 +Add Aggregation 按 键 添加 一 个 聚合 。buckets 聚 合 指明 从 你 的 数据 集中 将 要 检索 什么 信息 。 


在 你 选 定 一 个 buckets 聚 合 之 前 ， 先 指定 你 是 要 切割 单个 图 的 分 片 ， 还 是 切割 成 多 个 图 形 。 多 图 切 分 必须 在 其 他 聚合 之 前 


后 选择 Split Area 或 者 Split Chart， 并 从 类 型 菜单 中 选择 一 个 子 聚合 。 具 体 可 用 聚 


击 Rows|Columns 选 择 器 即 可 。 


图 形 的 X 轴 是 buckets 维 


度 。 你 可 以 为 X 轴 定义 buckets， 同 样 还 可 以 为 图 片上 的 分 片区 域 ,或 者 分 割 的 图 片 定义 buckets。 


该 图 形 的 X 轴 支持 的 聚合 ,与 18.4.1 节 “area” 一 致 。 


一 旦 你 定义 好 了 一 个 > 


聚合 ， 可 以 继续 定义 子 聚 合 来 完善 可 视 化 效果 。 点 击 +Add Sub Aggregation 添 加 子 聚 合 ， 然 


当 一 个 图 形 中 定义 了 多 个 聚合 ， 可 以 使 用 聚合 类 型 右 侧 的 上 下 箭头 来 改变 聚合 的 优先 级 。 


你 可 以 点 击 Advanced 链 接 显示 更 多 有 关 聚 合 的 


下 面 参数 是 否 可 用 ， 取 决 于 你 选择 的 聚合 函数 。 


选择 view options 更 改 表格 中 如 下 方面 : 


自 定义 参数 ， 这 部 分 和 18.4.1 节 “area” 一 致 。 


' Bar Mode: 当 你 为 自己 的 图 形 定义 了 多 个 Y 轴 聚合 时 ， 你 可 以 用 这 个 选项 决定 聚合 显示 的 方式 : 


- stacked: 依次 堆 又 聚合 效果 。 


percentage: 每 个 聚合 显示 为 总 和 的 百分比 。 


“ grouped: 用 最 低 优 先 级 的 子 聚合 的 结果 做 水 平分 组 。 


多 选 
* Sh 


“Sh 


* Scale Y-Axis to Data Bounds: 默认 的 Y 轴 长 度 为 0 到 数据 集 的 最 大 值 


框 可 以 用 来 控制 以 下 行为 : 


ow Tooltip: 勾 选 该 项 显示 工具 栏 。 


ow Legend: 勾 选 该 项 在 图 形 右 侧 显示 图 例 。 


运行 。 如 果 你 切 分 图 形 ， 你 可 以 选择 切 分 结果 是 展示 成 行 还 是 列 的 形式 ， 点 


后 选择 Split Area 或 者 Split Chart， 并 从 类 型 菜单 中 选择 一 个 子 聚合 。 


。 义 选 该 项 改变 Y 轴 的 最 大 和 最 小 值 为 数据 集 的 返回 值 。 


18.5 ”仪表 盘 功 能 


Kibana 中 的 dashboard 功 能 可 让 你 自由 排列 一 组 已 保存 的 可 视 化 。 然 后 你 可 以 保存 这 个 仪表 盘 ， 用 来 分 享 或 者 重 载 。 


简单 的 仪表 盘 如 图 18-13 所 示 。 
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18-13 dashboard f$] 


18.5.1 开始 


仪表 盘 ， 你 需要 至 少 有 一 个 已 保存 的 visualization。 下 面 是 几 个 功能 介绍 : 


: 创建 一 个 新 的 仪表 盘 。 你 第 一 次 点 击 Dashboard 标 签 的 时 候 ，Kibana 会 显示 一 个 空白 的 仪表 盘 ， 如 图 18-14 所 示 。 通 过 添加 可 视 化 的 方式 来 构建 你 的 仪表 盘 。 


Dashiboar 


Ready to get started? 


Cick Be C) button in the menu ter above to add a vimanlization to the dashboard. 
M you haven't setup a visualizaficn yst visit the "Viscalise* tab to create your first visualiration. 


E18-14. ZU dE 


: 添加 可 视 化 到 仪表 盘 上 。 和 要 添加 可 视 化 到 仪表 盘 上 ， 点 击 工 具 栏 面 板 上 的 Add Visualization an. 从 列表 中 选择 一 个 已 保存 的 可 视 化 。 你 可 以 在 Visualization Filter 里 输入 字符 串 来 过 滤 想 要 找 的 可 视 
化 。 由 你 选择 的 这 个 可 视 化 会 出 现在 你 仪表 盘 上 的 一 个 容器 (container) 里 。 如 果 你 觉得 容器 的 高 度 和 宽度 不 合适 ， 可 以 调整 容器 大 小 。 稍 后 有 详细 说 明 。 


: 保存 仪表 盘 。 要 保存 仪表 盘 ， 点 击 工 具 栏 面板 上 的 Save Dashboard 按 钮 ， 在 Save As 栏 输入 仪表 盘 的 名 字 ， 然 后 点 击 Save 按 钮 。 


:加载 已 保存 仪表 盘 。 点 击 Load Saved Dashboard 按 钮 显示 已 存在 的 仪表 盘 列 表 。 已 保存 仪表 盘 选择 器 包括 了 一 个 文本 栏 可 以 通过 仪表 盘 的 名 字 做 过 滤 ， 还 有 一 个 链接 到 Object Editor 而 已 管理 你 的 已 保存 
仪表 盘 。 你 也 可 以 直接 点 击 Settings 一 Edit Saved Objects 来 访问 Object Editors 


CERINGRR. MOT AZ EDU EIE LAUR Ps TUARA XEKibana 4 BUR fbi, TARAIRE. MP LMA Kibanaf] 37 IS ECC E78 SIC BUR dE. edi SharedAg EHTM, 3 
DETEVTETESTUPENRDIDESCU T PRTITTNEREPITSLPTPITAMEETTPEIC ET 
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18.5.2 ”容器 功能 
仪表 盘 里 的 可 视 化 都 存在 可 以 调整 大 小 的 “容器 ”里 ， 接 下 来 会 讨论 一 下 容器 功能 。 
“ 移动 容器 。 点 击 并 按 住 容器 的 顶部 ， 就 可 以 拖 动容 器 到 仪表 盘 任意 位 置 。 其 他 容器 会 在 必要 的 时 候 自 动 移动 ， 给 你 在 拖 动 的 这 个 容器 空 出 位 置 。 松 开 饼 标 ， 容 器 就 会 固定 在 当前 停留 位 置 。 
“ 改变 容器 大 小 。 移 动 光标 到 容器 的 右 下 角 ， 等 光标 变 成 指向 拐角 的 方向 ， 点 击 并 按 住 氮 标 ， 拖 动 改 变 容器 的 大 小 。 
: 删除 容器 。 点 击 容器 右上 角 的 x 图 标 删除 容器 。 从 仪表 盘 删 除 容器 ， 并 不 会 同时 删除 掉 容 器 里 用 到 的 已 存 可 视 化 。 


“ 查看 详细 信息 。 要 显示 可 视 化 背后 的 原始 数据 ， 点 击 容器 底部 的 条 带 。 可 视 化 会 被 有 关 原 始 数据 详细 信息 的 几 个 标签 替换 掉 。 标 签 包 括 : 表格 、 请 求 、 统 计 值 ， 下 面 分 别 介绍 


介绍 


:表格 (Table) 。 底 层 数 据 的 分 页 展示 。 你 可 以 通过 点 击 每 列 顶部 的 方式 给 该 列 数据 排序 ， 如 图 18-15 所 示 。 


NYCTA: Injury count by type Manhattan 


W 


filters $ 

numbar of cyclist injured-[1 TO 7 
number of motorist injured:[1 TO *] 
number of pedestrians injured:[1 TO *] 


number of parsons injured:[1 TO *] 


图 18-15 ”数据 表格 


- 请 求 (Request) 。 发 送 到 服务 器 的 原始 请 求 ， 以 JSON 格 式 展示 ， 如 图 18-16 所 示 。 


NYCTA: Injury count by type Manhattan 


x 


parch request body 


"sire": B, 
"aggs" : 1 
uan. t 
"filters": { 
"Filters": { 
"number of cyclist injured:[1 TO x]"; 4 
"quary" : £ 
"query. string": d 
"query": "number of cyclist injured: [1 TO x]", 
"analyze wildcard": true 
} 
} 
F 
"number of motorist injured: [1 TO x]": 4d. 
"quary'': { 
"query string": 1 
"query": "number of motorist injured: [1 TO x]", 
"analyze wildcard": true 


图 18-16 请 求 数据 


. 响应 (Response) 。 从 服务 器 返回 的 原始 响应 ， 同 样 以 SON 格 式 展示 ， 如 图 18-17 所 示 。 


NYCTA: Injury count by type Manhattan 


"took": 32, 
"timed out": false, 
" shards": 1 
"total": 5, 
"successful": 5, 
"failed": 6 
Fa 
"hits": { 
"total": 947, 
"max score": 8, 
"hits": [] 
), 
"aggregations": 1 
nga 1 
"buckets": { 
"number of cyclist injured:[1 TO x]": { 
"doc count": 25 
Fr 
"number of motorist injured:[1 TO «]": { 
"doc count": 41 
F: 


图 18-17 原始 响应 


: 统计 值 (Statistics) 。 和 请 求 响应 相关 的 一 些 统计 值 ， 以 数据 网 格 的 方式 展示 。 包 括 数 据 报 告 、 请 求 时 间 、 响 应 时 间 、 返 回 的 记录 条 目 数 、 匹 配 请 求 的 索引 模式 (index pattern) ， 如 图 18-18 所 示 。 


N'YCTA: Injury count by type Manhattan 


had 


Query Duration 


Request Duration 


图 18-18 表格 显示 
18.5.3 ”修改 可 视 化 


点 击 容器 右上 角 的 Edit 按 钮 在 Visualize 页 打开 可 视 化 编辑 。 


18.6 Setting 功能 


使 用 Kibana， 你 就 得 告诉 它 你 想 要 探索 的 Elasticsearch 索 引 是 哪些 ， 这 就 要 配置 一 个 或 者 更 多 的 索引 模式 。 此 外 ， 你 还 可 以 进行 以 下 操作 : 

: 创建 脚本 化 字段 ， 这 个 字段 可 以 实时 从 你 的 数据 中 计算 出 来 。 你 可 以 浏览 这 种 字段 ， 并 且 在 其 基础 上 做 可 视 化 ， 但 是 不 能 搜索 这 种 字段 。 

“ 设置 高 级 选项 ， 比 如 表格 里 显示 多 少 行 ， 常 用 字段 显示 多 少 个 。 修 改 高 级 选项 的 时 候 要 千 万 小 心 ， 因 为 一 个 设置 很 可 能 跟 另 一 个 设置 是 不 兼容 的 。 
“ 为 生产 环境 配置 Kibana。 


下 面 逐 一 介绍 Setting 功 能 。 
18.61 创建 一 个 连接 到 Elasticsearch 的 索引 模式 


索引 模式 定义 了 一 个 或 者 多 个 你 打算 探索 的 Elasticsearch 索 引 。Kibana 会 查找 匹配 指定 模式 的 索引 名 。 模 式 中 的 通配符 (*) 匹配 零 到 多 个 字符 。 比 如 ， 模 式 myindex-* 匹 配 所 有 名 字 以 myindex- 开 头 
的 索引 ， 如 myindex-1 和 myindex-2。 


如 果 你 用 了 事件 时 间 来 创建 索引 名 (比如 ， 如 果 你 是 用 Logstash 往 Elasticsearch 里 写 数据 ) ， 索 引 模 式 里 也 可 以 匹配 一 个 日 期 格式 。 在 这 种 情况 下 ， 模 式 的 静态 文本 部 分 必须 用 中 括号 包含 起 来 ， 日 期 
格式 能 用 的 字符 ， 参 见 表 18-3。 


表 18-3 日 期 格式 码 


D MEE: 
Month - cardinal: 1 2 3 … 12 
Month - ordinal: 1st 2nd 3rd … 12th 
Month - two digit: 01 02 03 … 12 
Month - abbreviation: Jan Feb Mar … Dec 
Month - full: January February March … December 
Quarter: 12 34 
Day of Month - cardinal: 1 2 3 … 31 
Day of Month - ordinal: 1st 2nd 3rd … 31st 
Day of Month - two digit: 01 02 03 --- 31 
Day of Year - cardinal: 1 2 3 … 365 
Day of Year - ordinal: 1st 2nd 3rd … 365th 
Day of Year - three digit: 001 002 … 364 365 


比如 ，[logstash-]YYYY.MM.DD 匹 配 所 有 名 字 以 logstash -为 前 缀 ， 后 面 跟 上 YYYY.MM.DD 格 式 时 间 戳 的 索引 ， 比 如 logstash-2015.01.31 和 logstash-2015-02-01。 


索引 模式 也 可 以 简单 地 设置 为 一 个 单独 的 索引 名 字 。 
要 创建 一 个 连接 到 Elasticsearch 的 索引 模式 ， 应 如 下 操作 : 


1) 切换 到 Settings 一 Indices 标 签 页 。 


D MS: 
Day of Week - cardinal: 0 1 3 --- 6 
Day of Week - ordinal: Oth 1st 2nd … 6th 
Day of Week - 2-letter abbreviation: Su Mo Tu … Sa 
Day of Week - 3-letter abbreviation: Sun Mon Tue … Sat 
Day of Week - full: Sunday Monday Tuesday *… Saturday 
Day of Week (locale): 0 12 =- 6 
Day of Week (ISO): 123-7 
Week of Year - cardinal (locale): 1 2 3 … 53 
Week of Year - ordinal (locale): 1st 2nd 3rd .… 53rd 
Week of Year - 2-digit (locale): 01 02 03 … 53 
Week of Year - cardinal (ISO): 1 2 3 --- 53 
Week of Year - ordinal (ISO): 1st 2nd 3rd +- 53rd 
Week of Year - two-digit (ISO): 01 02 03 … 53 
Year - two digit: 70 71 72 --- 30 
Year - four digit: 1970 1971 1972 + 2030 
Week Year - two digit (locale): 70 71 72 --- 30 
Week Year - four digit (locale): 1970 1971 1972 … 2030 
Week Year - two digit (ISO): 70 71 72 … 30 
Week Year - four digit (ISO): 1970 1971 1972 --- 2030 
AM/PM: AM PM 
am/pm: am pm 
Hour. 012 --- 23 
Hour - two digit: 00 01 02 … 23 
Hour - 12-hour clock: 1 2 3 … 12 
Hour - 12-hour clock, 2 digit: 01 02 03 … 12 
Minute: 0 12 --- 59 
Minute - two-digit: 00 01 02 … 59 
Second: 012 --- 59 
Second - two-digit: 00 01 02 … 59 
Fractional Second - 10ths: 0 12 --- 9 
Fractional Second - 100ths: 0 1 … 98 99 
Fractional Seconds - 1000ths: 0 1 --- 998 999 


(8 ) 


Timezone - zero UTC offset (hh:mm format): -07:00 -06:00 -05:00 .. +07:00 
Timezone - zero UTC offset (hhmm format): -0700 -0600 -0500 … +0700 


Unix Timestamp: 1360013296 
Unix Millisecond Timestamp: 1360013296123 


2) 指定 一 个 能 匹配 你 的 Elasticsearch 索 引 名 的 索引 模式 。 默 认 情 况 下 ，Kibana 会 假设 你 是 要 处 理 Logstash 导 入 的 数据 。 


Qs 


当 你 在 顶层 标签 页 之 间 切 换 的 时 候 ，Kibana 会 记 住 你 之 前 停留 的 位 置 。 比 如 ， 如 果 你 在 Settings 标 签 页 查看 了 一 个 索引 模式 ， 然 后 切换 到 Discover 标 签 ， 再 切换 回 Settings 标 签 ，Kibana 还 会 显示 上 次 你 查看 
的 索引 模式 。 要 看 到 创建 模式 的 表单 ， 需 要 从 索引 模式 列表 里 点 击 Add 按 钮 。 


3) 如 果 你 索引 有 时 间 惟 字段 打算 用 来 做 基于 事件 的 对 比 ， 勾 选 Index contains time-based events 然 后 选择 包含 了 时 间 戳 的 索引 字段 。Kibana 会 读 取 索引 映射 ， 列 出 所 有 包含 了 时 间 戳 的 字段 供 选 


择 。 


4) 如 果 新 索引 是 周期 性 生成 ， 名 字 里 有 时 间 戳 的 ， 勾 选 Use event times to create index names 和 Index pattern interval 选 项 。 这 会 让 Kibana 只 搜索 哪些 包含 了 你 指定 的 时 间 范 围 内 的 数据 的 索引 。 
当 你 使 用 Logstash 往 Elasticsearch 写 数据 的 时 候 非 常 有 用 。 


5) 点 击 Create 添 加 索引 模式 。 
6) 要 设置 新 模式 作为 你 查看 Discover 页 是 的 默认 模式 ， 点 击 favorite 按 钮 。 


下 面 介 绍 几 个 设置 选项 。 


1. 设 置 默认 索引 模式 


默认 索引 模式 会 在 你 查看 Discover 标 签 的 时 候 自动 加 载 。Kibana 会 在 Settings 一 Indices 标 签 页 的 索引 模式 列表 里 ， 给 默认 模式 左边 显示 一 个 星 号 。 你 创建 的 第 一 个 模式 会 自动 设置 为 默认 模式 。 


要 设置 一 个 另外 的 模式 为 默认 索引 模式 ， 应 如 下 操作 : 
1) 进入 Settings 一 Indices 标 签 页 。 


2) 在 索引 模式 列表 里 选择 你 打算 设置 为 默认 值 的 模式 。 


3) 点 击 模式 的 Favorite 标 签 。 


尔 也 可 以 在 Advanced 一 Settings 里 设置 默认 索引 模式 。 


c 
2 


2. 重 加 载 索引 的 字段 列表 


当 你 添加 了 一 个 索引 映射 ，Kibana 自 动 扫描 匹配 模式 的 索引 以 显示 索引 字段 。 你 可 以 重 加 载 索 引 字段 列表 ， 以 显示 新 添加 的 字段 。 


重 加 载 索 引 字段 列表 ， 也 会 重 设 Kibana 的 常用 字段 计数 器 。 这 个 计数 器 是 跟踪 你 在 Kibana 里 常用 字段 ， 然 后 来 排序 字段 列表 的 。 


要 重 加 载 索引 的 字段 列表 ， 应 如 下 操作 : 


1) 进入 Settings 一 Indices 标 签 页 。 


N 


在 索引 模式 列表 里 选择 一 个 索引 模式 。 


3) 点 击 模式 的 Reload 按 钮 。 


w 


出 除 一 个 索引 模式 


要 删除 一 个 索引 模式 ， 应 如 下 操作 : 


A 


进入 Settings 一 Indices 标 签 页 。 


2) 在 索引 模式 列表 里 选择 你 打算 删除 的 模式 。 


3) 点 击 模式 的 Delete 按 钮 。 


4) 确认 你 是 想 要 删除 这 个 索引 模式 。 


18.6.2 ”创建 一 个 脚本 化 字段 


脚本 化 字段 从 你 的 Elasticsearch 索 引 数 据 中 即时 计算 得 来 。 在 Discover 标 签 页 ， 脚 本 化 字段 数据 会 作为 文档 数据 的 一 部 分 显示 ， 而 且 你 还 可 以 在 可 视 化 里 使 用 脚本 化 字段 。 (脚本 化 字段 的 值 是 在 请 求 
的 时 候 计 算 的 ， 所 以 它们 没有 被 索引 ， 不 能 搜索 到 。) 


Os 


即时 计算 脚本 化 字段 非常 消耗 资源 ， 会 直接 影响 到 Kibana 的 性 能 。 而 且 记 住 ，Elasticsearch 里 没有 内 置 对 脚本 化 字段 的 验证 功能 。 如 果 你 的 脚本 有 bug， 你 会 在 查看 动态 生成 的 数据 时 看 到 exception。 


脚本 化 字段 使 用 Lucene 表 达 式 语法 。 更 多 细节 ， 请 阅读 Lucene Expressions Scripts, 


你 可 以 在 表达 式 里 引用 任意 单个 数值 类 型 字段 ， 比 如 : 


doc['field name'].value 


要 创建 一 个 脚本 化 字段 ， 应 如 下 操作 : 

1) 进入 Settings 一 Indices 

2) 选择 你 打算 添加 脚本 化 字段 的 索引 模式 。 
3) 进入 模式 的 Scripted Fields 标 签 。 


4) 点 击 Add Scripted Field。 


5) 输入 脚本 化 字段 的 名 字 。 


6) 输入 用 来 即时 计算 数据 的 表达 式 。 


7) 点 击 Save Scripted Field。 


有 关 Elasticsearch 的 脚本 化 字段 的 更 多 细节 ， 阅 读 http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-scripting.html。 


要 更 新 一 个 脚本 化 字段 ， 应 如 下 操作 : 
1) 进入 Settings 一 Indices。 
2) 点 击 你 要 更 新 的 脚本 化 字段 的 Edit 按 钮 。 


3) 完成 变更 后 点 击 Save Scripted Field 升 级 。 


Qus 


Elasticsearch 里 没有 内 置 对 脚本 化 字段 的 验证 功能 。 如 果 你 的 脚本 有 bug， 你 会 在 查看 动态 生成 的 数据 时 看 到 exception。 


要 删除 一 个 脚本 化 字段 ， 应 如 下 操作 : 
1) 进入 Settings 一 Indices。 
2) 点 击 你 要 删除 的 脚本 化 字段 的 Delete 按 钮 。 


3) 确认 你 确实 想 删 除 它 。 


18.6.3 ”设置 高 级 参数 


高 级 参数 页 允许 你 直接 编辑 那些 控制 着 Kibana 应 用 行为 的 设 


© 


n 


r 
A 


。 比 如 ， 你 可 以 修改 显示 


期 的 格式 ， 修 改 默认 的 索引 模式 ， 设 置 十 进 制 数值 的 显示 精度 。 


修改 高 级 参数 可 能 带 来 意 想不到 的 后 果 。 如 果 你 不 确定 自己 在 做 什么 ， 最 好 离开 这 个 设置 页 面 。 


要 设置 高 级 参数 ， 应 如 下 操作 : 
1) 进入 Settings 一 Advanced。 
2) 点 击 你 要 修改 的 选项 的 Edit 按 钮 。 
3) 给 这 个 选项 输入 一 个 新 的 值 。 


4) 点 击 Save 按 钮 。 


18.64 ”管理 已 保存 的 搜索 、 可 视 化 和 仪表 盘 


你 可 以 从 settings 一 Objects 查 看 、 编 辑 和 删除 已 保存 的 搜索 、 


查看 一 个 已 保存 的 对 象 会 显示 在 Discover、Visualize 或 Dashboard 页 旦 


1) 进入 Settings 一 Objects。 
2) 选择 你 想 查看 的 对 象 。 


3) 点 击 View 按 钮 。 


可 视 化 和 仪表 盘 。 


已 选择 的 项 目 。 要 查看 一 个 已 保存 对 象 ， 应 如 下 操作 : 


编辑 一 个 已 保存 对 象 让 你 可 以 直接 修改 对 象 定义 。 你 可 以 修改 对 象 的 名 字 ， 添 加 一 段 说 明 ， 以 及 修改 定义 这 个 对 象 的 属性 的 JSON。 


如 果 你 尝试 访问 一 个 对 象 ， 而 它 关联 的 索引 已 经 被 删除 了 ，Kibana 会 显示 这 个 对 象 的 编辑 (Edit Object) 页 。 你 可 以 进行 如 下 操作 : 


: 重建 索引 这 样 就 可 以 继续 用 这 个 对 象 。 
“ 删除 对 象 ， 然 后 用 另 一 个 索引 重建 对 象 。 


- 在 对 象 的 kibanaSavedObjectMeta.seatchSourceJSON 里 修改 引用 


的 索引 名 ， 指 向 一 个 还 存在 的 索引 模式 。 这 个 在 你 的 索引 被 重 命名 了 的 情况 下 非常 有 用 。 


对 象 属性 没有 验证 机 制 。 提 交 一 个 无 效 的 变更 会 导致 对 象 不 可 


要 编辑 一 个 已 保存 的 对 象 ， 应 如 下 操作 : 


EN 


进入 Settings 一 Objects。 


2) 选择 你 想 编辑 的 对 象 。 


Ww 


点 击 Edit 按 钮 。 


4) 修改 对 象 定义 。 


5) 点 击 Save Object 按钮 。 


要 删除 一 个 已 保存 的 对 象 ， 应 如 下 操作 : 


。 通 常 来 说 ， 你 还 是 应 该 


Discover、Visualize 或 Dashboard 页 面 来 创建 新 对 象 而 不 是 直接 编辑 已 存在 的 对 象 。 


1) 进入 Settings 一 Objects。 


2) 选择 你 想 删 除 的 对 象 。 


3) 点 击 Delete 按 钮 。 


4) 确认 你 确实 想 删除 这 个 对 象 。 


18.7 


Kibana 服 务 器 在 启动 的 时 候 会 从 kibana.yml 文 件 读 取 | 
你 还 可 以 开启 SSL 或 者 设置 其 他 一 系列 选项 。 具 体 


18.8 


设置 Kibana 服 务 器 属性 


属 性 
port 
host 
elasticsearch url 
属 性 


elasticsearch preserve host 


kibana index 


default app id 


request timeout 


shard timeout 
verify ssl 
ca 


ss] key file 


ss] cert file 


pid file 


常用 sub agg 示 例 


属性 设置 。 默 认 设 置 是 运行 在 localhost: 5601。 要 变更 主机 或 端口 ， 或 者 连接 远 端 主机 上 的 Elasticsearch， 你 都 需要 更 新 你 的 kibana.yml 文 件 。 


属性 描述 见 表 18-4: 


表 18-4 Kibana 服 务 器 属性 


描 述 
Kibana 服务 器 运行 的 端口 。 默 认 : port: 5601. 
Kibana 服务 器 监听 的 地 址 。 默 认 : host: "0.0.0.0". 


你 想 请 求 的 索引 存在 哪个 Elasticsearch 实例 上 。 默 认 : 
localhost:9200" . 


elasticsearch url: "http:// 


(5 ) 
4H 述 

默认 的 ， 浏览 器 请 求 中 的 主机 名 即 作为 Kibana 发 送 给 Elasticsearch 时 请 求 的 主 
机 名 。 如 果 你 设置 这 个 参数 为 false，Kibana 会 改 用 elasticsearch_url 里 的 主机 名 。 
你 应 该 不 用 担心 这 个 设置 一 一 直接 用 默认 即 可 。 默 认 : elasticsearch preserve_ 
host: true, 

保存 搜索 ,可视化 ， 仪 表盘 信息 的 索引 的 名 字 。 默 认 : kibana index: kibana. 

YE À Kibana 是 默认 显示 的 页 面 。 可 以 为 discover，visualize，dashboard 或 
settings。 默 认 : default app id: "discover". 

等 待 Kibana 后 端 或 Elasticsearch 的 啊 应 的 超时 时 间 ， 
request timeout: 500000. 


Elasticsearch 等 待 分 片 啊 应 的 超时 时 间 。 设 置 为 0 表示 关闭 超时 控制 。 默 认 : 
shard timeout: 0, 

定义 是 否 验 证 Elasticsearch SSL HE B, E EE 7j false X P] SSL i HE, EA iA: 
verify ssl true. 

你 的 Elasticsearch 实例 的 CA 证 书 的 路 径 。 如 果 你 是 自己 签 的 证 书 ， 必 须 指定 
这 个 参数 ,证 书 才能 被 认证 。 和 否则 ， 你 需要 关闭 verify_ssl。 默 认 : none. 

Kibana 服务 器 的 密 钥 文件 路 径 。 设 置 用 来 加 密 浏 览 器 和 Kibana 之 间 的 通信 。 
默认 : none. 

Kibana 服务 器 的 证 书 文 件 路 径 。 设 置 用 来 加 密 浏 览 器 和 Kibana 之 间 的 通信 。 
默认 : none。 

你 想 用 来 存 进程 ID 文件 的 位 置 。 如 果 没 有 指定 ，PID 文件 存在 /var/run/kibana. 
pid。 默 认 : none. 


单位 毫秒 。 默 认 : 


本 章 开始 ， 就 提 到 K4 和 K3 的 区 别 ， 在 K4 中 ， 即 便 介绍 完了 全 部 visualize 的 配置 项 ， 也 不 代表 用 户 能 立刻 上 手 配置 出 来 和 K3 一 样 的 面板 。 所 以 本 节 会 以 几 个 具体 的 日 志 分 析 需 求 为 例 ， 演 示 在 K4 中 ， 
用 Elasticsearch 1.0 以 后 提供 的 Aggregation 特 性 ， 能 够 做 到 哪些 有 用 的 可 视 化 效果 。 


— 


18.8.1 ”函数 堆栈 链 分 析 
本 书 之 前 已 经 介绍 过 Logstash 如 何 利用 multiline 或 者 log4j 插 件 解析 函数 堆栈 。 那 么 ， 对 函数 堆栈 ， 我 们 除了 对 底层 函数 做 基础 的 topN 排 序 ， 还 能 深入 发 气 出 来 什么 信息 呢 ? 


图 18-19 是 一 个 PHP 慢 函数 堆栈 的 可 视 化 统计 : 


该 图 利用 了 Kibana 4 的 sub aggs 特 性 。 按 照 分 层次 的 函数 堆栈 ， 逐 层 做 terms agg。 得 到 一 个 类 似 火焰 图 效果 的 干 层 饼 效 果 。 
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图 18-19 1 BAER 


和 火焰 图 不 同 的 是 ， 干 层 饼 并 不 能 自动 深入 到 函数 堆栈 的 全 部 层次 ， 需 要 自己 手动 指定 聚合 到 第 几 层 。 考 虑 到 重复 操作 在 页 面 上 不 是 很 方便 。 可 以 利用 Kibana 4 的 url 里 自 带 rison 序 列 化 配置 项 的 特 
性 ， 直 接 修改 地 址 生成 效果 。 图 18-19 的 url 如 下 : 


http://k4domain:5601/#/visualize/edit/php-slow-stack-pie? g- () & a= (filters:! () , linked:!t,query: (query string: (query:'* ') ) , vis: (aggs:! ( (id:'1',params: () , schema:met. 


可 以 看 到 ， 如 果 打 算 增 减 堆栈 的 聚合 层次 ， 对 应 增 减 一 段 (id: '5', params: (field: slow.4, order: desc, orderBy: '1', size: 10) ， 就 可 以 了 。 


作为 固定 可 视 化 分 析 模 式 的 另 一 种 分 享 办 法 ， 还 可 以 导出 该 visualize object 在 .kibana 索 引 中 的 JSON 记 录 。 这 样 其 他 人 只 需要 原样 再 导入 到 自己 的 .kibana 索 引 即 可 : 


# curl -XGET 127.0.0.1: 9200/. kibana/visualization/php- slow-stack-pie/ source 
{ “title” : "php-slow-stack-pie' , 'visState" : “{\” aggsV ":[(V. id\ ":V' 1\ “,\” params\ ":(), V schema\ “:\” metric\ ",V' type\ “:\” county "), (V. idN “V 2\ ", V paramsy ":(V fit 


上 面 记录 中 可 以 看 到 ， 这 个 visualize 还 关联 了 一 个 savedSearch， 那 么 同样 ， 再 从 .kibana 索 引 里 把 这 个 内 容 也 导出 : 


4 curl .XGET 127.0.0.1:9200/. kibana/search/php- pmsl ou og source 
{ "title" : "php-fpm-slowlog' , “description” : ts" :0, “columns” :[ " source' ], “sort” :[ "étimestamp' , “desc” ], “version” :1, "kibanaSavedObjectMeta" :( "searchSourceJSO 


这 个 内 容 看 起 来 有 点 怪 怪 的 ， 其 实 把 searchSourceJSON 字 符 串 复制 出 来 ， 在 终端 下 贴 到 echo-ne 命 令 后 面 ， 回 车 即 可 看 到 其 实 是 这 样 : 


“index” : “[logstash-mweibo-]YYYY.MM.DD” , 
“highlight” HE 
"pre tags" : [ 
"Qkibana-highlighted-fielde" 
l; 
"post | tags" : [ 
"Q/kibana-highlighted-field8" 


l; 
fields” : { 
a”. 


filter [ 
meta { 
“index” : “[logstash-mweibo-]YYYY.MM.DD” , 
“negate” : Herr 
“key: $ 
“value” : -ae fpm-slow" š 


"disabled" : false 


: “php-fpm-slow” , 
“phrase” 


} 
} 
} 
lp. os 
query : { . 
query string : ( 
"query  ; ^", 
"analyze wildcard" : true 
} 
} 
} 


18.82 分 图 统计 


上 一 节 我 们 展示 了 sub aggs 在 饼 图 上 的 效果 。 不 过 这 多 层 agg 其 实用 的 是 同一 类 数据 。 如 果 在 聚合 中 ， 要 加 上 一 些 完全 不 同 纬度 的 数据 ， 还 是 在 单一 的 图 片上 继续 累加 就 不 是 很 直观 了 。 比 如 说 ， 还 是 
上 一 节 用 到 的 PHP 慢 函数 堆栈 。 我 们 可 以 根据 机 房 做 一 下 拆 分 。 由 于 代码 部 署 等 主动 变更 都 是 有 灰 度 部 署 的 ， 一 旦 发 现 某 机 房 有 异常 ， 就 可 以 及 时 处 理 了 。 


同样 还 是 新 建 sub aggs， 但 是 在 开始 ， 选 择 split chart 而 不 是 split slice， 如 图 18-20 所 示 。 


图 18-20 ”分 图 配置 


从 URL 里 可 以 看 到 ， 分 图 的 aggs 是 schema: split， 而 饼 图 分 片 的 aggs 是 schema: segment: 


http: //k4domain:5601/4/visualize/edit/php-slow-stack-pie? g- (refreshInterval: (display:Off,pause: !f,section:0,value:0) , time: (from:now-12h,mode:quick,to:now) ) & a- (filters:! 


18.8.3 ”TopN 的 时 序 趋势 图 


TopN 的 时 序 趋势 图 是 将 ELK stack 用 于 监控 场景 最 常用 的 手段 。 乃 至 在 Kibana 3 时 代 ， 开 发 者 都 通过 在 Query 框 上 额外 定义 TopN 输 入 的 方式 提供 了 这 个 特性 。 不 过 在 Kibana 4 中 ， 因 为 sub aggs 的 依 
次 分 桶 原理 ，TopN 时 序 趋势 图 又 有 了 新 的 特点 。 


Kibana 3 中 ， 请 求实 质 是 先 单独 发 起 一 次 termFacet 请 求 得 到 topN， 然 后 再 发 起 带 有 facetFilter 的 dateHistogramFacet， 分 别 请 求 每 个 term 的 时 序 。 那 么 同样 的 原理 ， 迁 移 到 Kibana 4 中 ， 就 是 先 利 
用 一 次 termAgg 分 桶 后 ， 再 每 个 桶 内 做 dateHistogramAgg 了 。 对 应 的 Kibana 4 地 址 为 : 


http: //k4domain:5601/f/visualize/edit/php-fpm-slowlog-histogram? g- (refreshInterval: (display:Off,pause:!f,section:0,value:0) , time: (from:now-12h,mode:quick,to:now) ) & a- (fi 


效果 如 图 18-21 所 示 。 


可 以 看 到 图 上 就 是 3 根 线 ， 分 别 代表 top3 的 host 的 时 序 。 


一 般 来 说 ， 这 样 都 是 够 用 的 。 不 过 如 果 经 常 有 host 变 动 的 时 候 ， 在 这 么 大 的 一 个 时 间 范 围 内 ， 求 一 次 总 的 topN， 可 能 就 淹没 了 一 些 瞬 间 的 变动 了 。 所 以 ， 在 Kibana 4E, 我们 可 以 把 sub aggs 的 顺序 
颠倒 一 下 。 先 按 dateHistogramAgg 分 桶 ， 再 在 每 个 时 间 桶 内 ， 做 termAgg。 对 应 的 Kibana 4 地 址 为 : 


http://k4domain:5601/#/visualize/edit/php-fpm-slowlog-histogram?_g= (refreshInterval: (display:Off,pause:!f,section:0,value:0) , time: (from:now-12h,mode:quick,to:now) ) & a- (fi 


可 以 对 比 一 下 前 一 条 url， 其 中 就 是 把 id 为 2 和 3 的 两 段 做 了 对 调 ， 而 最 终 效果 如 图 


Deqten memi TY Y Y MY En 


差距 多 么 明显 ! 


18.8.4 响 


应 时 间 的 百 分 占 比 趋 势 图 


时 序 图 除了 上 节 展 示 的 最 基本 的 计数 以 外 ， 还 可 以 在 Y 轴 上 使 用 其 他 数值 统计 结果 。 


18-21 top host 示 例 


18-22 所 示 。 


图 18-22 top date 示 例 


最 常见 的 ， 比 如 访问 日 志 的 平均 响应 时 间 。 但 是 平均 值 在 数学 统计 中 ， 是 一 个 非常 不 可 信 的 数据 ， 稍 微 几 个 远离 置信 


区 间 的 数值 就 可 以 严重 影响 到 平均 值 。 所 以 ， 在 评价 数值 的 总 体 分 布 情况 时 ， 更 推荐 采 


Kibana 4 没有 箱 体 图 的 可 视 化 方式 。 不 过 采用 线 图 ， 我 们 一 样 可 以 做 到 类 似 的 效果 。 


在 上 一 章 的 时 序数 据 基 础 上 ， 改 变 Y 轴 数据 源 ， 选 择 Percentile 方 式 ， 然 后 输入 具体 的 四 分 位 。 运 行 泻 染 即 可 ， 如 


9 分 位 数 ， 也 就 是 25%、50%、75%。 在 可 视 化 方面 ， 一 般 采 


图 18-23 所 示 。 


箱 体 图 


方式 。 


>o a 一 人 下 s Remi oa term. eui carbo 


Pert 一 om TOC MM DD 


418-23 5724 


对 比 新 的 URL， 可 以 发 现 变化 的 就 是 id 为 1 的 片段 。 变 成 了 (id: '1', params: (field: connect ms, percents: ! (50, 75, 95, 99) ) , schema: metric, type: percentiles) : 


http://k4domain:5601/#/visualize/create?type=areaśsavedSearchId=curldebug&_g= () & a- (filters:! () , linked:!t,query: (query string: (query:'* ') ) , vis: (aggs:! ( (id:'1',param: 


实践 表明 ， 在 访问 日 志 数 据 上 ,平均 数 一 般 相近 于 75% 的 四 分 位 数 。 所 以 ， 为 了 更 细 化 性 能 情况 ， 我 们 可 以 改 用 诸如 90%、95% 这 样 的 百 分 位 。 


此 外 ， 从 Kibana 4.1 开 始 ， 新 加 入 了 Percentile_rank 聚 合 支持 。 可 以 在 Y 轴 数据 源 里 选择 这 种 聚合 ， 输 入 具体 的 响应 时 间 ， 比 如 2s。 则 可 视 化 数据 变 成 2s 内 完成 的 响应 数 占 总 数 的 百分比 的 趋势 


IR] 


18.8.5 ”响应 时 间 的 概率 分 布 在 不 同时 段 的 相似 度 对 比 


前 面 已 经 用 百 分 位 的 时 序 ， 展 示 如 何 更 准确 的 监控 时 序数 据 的 波动 。 那 么 ， 还 能 不 能 更 进一步 呢 ? 在 制定 SLA 的 时 候 ， 制 定 报警 阔 值 的 时 候 ， 怎 么 才能 确定 当前 服务 的 拐点 ”除了 压 测 以 外 ， 我 们 还 可 
以 拿 线 上 服务 的 实际 数据 计算 一 下 概率 分 布 。Kibana 4 对 此 提供 了 直接 的 支持 ， 我 们 可 以 以 数值 而 非 时 间作 为 X 轴 数据 。 


那么 进一步 ， 我 们 怎么 区 分 不 同 产品 在 同一 时 间 ， 或 者 相同 产品 在 不 同时 间 ， 性 能 上 有 无 渐变 到 质变 的 可 能 ? 这里， 我 们 可 以 采用 grouped 方 式 ， 来 排列 filter aggs 的 结果 ， 如 图 18-24 所 示 。 
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图 18-24 ”分 组 对 比 


我 们 可 以 看 出 来 ， 虽 然 两 个 时 间 段 ， 响 应 时 间 是 有 一 定 差距 的 ， 但 是 是 整体 性 的 抬升 ， 没 有 明显 的 异 变 。 


当然 ， 如 果 觉 得 目测 不 靠 谱 的 ， 可 以 把 两 组 数值 拿 下 来 ， 通 过 PDL、scipy、matlab、R 等 工具 做 具体 的 差异 显著 性 检测 。 这 就 属于 后 续 的 二 次 开发 了 。 


filter 中 ， 可 以 写 任 意 的 query string 语 法 。 不 限于 本 例 中 的 时 间 段 : 


http://k4domain:5601/f/visualize/create?type-histogram&indexPattern-$5Blogstash- mweibo-nginx-$5DYYYY.MM.DD& g- () & a- (filters:! () , linked:!f,query: (query string: (analyze w 


189 ”Kibana 报 表 的 快速 实现 


ELK stack 本 身 作为 一 个 实时 数据 检索 聚合 的 系统 ， 在 定期 报表 方面 ， 是 有 一 定 劣势 的 。 因 为 基本 上 不 可 能 把 源 数 


询 一 次 过 久 的 冷 数据 ， 也 是 有 额外 消耗 的 。 那 么 ， 对 这 种 报表 数据 的 需求 ， 如 何 处 理 ? 其 实 很 简单 ， 把 整个 Kibana 页 


面 截图 


FireFox 有 插件 用 来 截取 全 网 页 图 。 不 过 如 果 作为 定期 的 工作 ， 这 么 搞 还 是 比较 麻烦 的 ， 需 要 脚本 化 下 来 。 这 时 候 计 


通过 js 程序 操作 webkit 浏 览 器 引擎 ， 实 现 各 种 浏览 器 功能 。 


phantomjs 在 Linux 平 台 上 没有 二 进 制 分 发 包 ， 所 以 必须 源 代码 编译 : 


居 长 期 保存 在 Elasticsearch 集 群 中 。 即 便 保存 了 ， 为 了 一 些 已 经 成 形 的 数据 ， 再 全 面 查 
下 来 即 可 。 


可 以 用 上 phantomjs 软 件 了 。phantomjs 是 一 个 基于 webkit 引 警 做 的 js 脚本 库 。 可 以 


# yum -y install gcc gcc-c++ make flex bison gperf ruby \ 
openssl-devel freetype-devel fontconfig-devel libicu- evel sqlite-devel V 
libpng-devel libjpeg-devel 

4 git clone git://github.com/ariya/phantomjs.git 

# cd phantomjs 

# git checkout 2.0 

# ./build.sh 


想 要 给 Kibana 页 面 截 


， 几 行 代码 就 够 了 。capture-kibana.js 示 例如 下 : 


IR] 


var page = require ( ‘webpage’ ) . create () ; 
var address = 'http: //kibana. example. con/ &/dashboard/elasticsearch/h5 : view'; 
var output = 'kibana.png'; 
page.viewportSize = ( width: 1366, height: 600 }; 
page.open (address, function (status) { 
if (status !== 'success ') 
console.log ('Unable to load the address!’ ) ; 
phantom.exit () ; 
) else ( 
window.setTimeout (function () { 
page.render (output) ; 
phantom.exit () ; 
), 30000) ; 


pi 


网 


片 了 。 


生成 的 kibana.png| 


然后 运行 phantomjs capture-kibana.js 命 令 ， 就 能 得 到 截 


区 


这 里 有 两 个 要 点 : 


1) 要 设置 viewportSize 里 的 宽度 ， 否 则 效果 会 变 成 单个 panel 依 次 往 下 排列 。 


2) 要 设置 setTimeout， 否 则 在 获取 完 index.html 后 就 直接 返回 了 ， 只 能 看 到 一 个 大 白板 。 用 phantomjs 截 取 angularjs 这 类 单 页 MVC 框 架 应 上 


Phantomjs 截 图 这 个 方法 ， 不 单 适用 于 Kibana4， 在 Kibana3 上 同样 适 


第 19 章 ”Kibana 4 源码 解析 


Kibana 4 采用 Angularjs+ Nodejjs 框 架 编写 。 其 中 Node,js 主 要 提供 两 部 分 功能 ， 给 Elasticsearch 做 搜索 请 求 转发 代理 ， 以 及 作为 auth、ssl、 


本 章 假设 你 已 经 对 Angular 有 一 定 程度 了 解 


如 果 打 算 迁 移 Kibana 3 的 CAS 验 证 功能 到 Kibana 4， 那 么 可 以 稍微 了 解 一 下 index.js、app.js、lib/auth.js 里 的 htpasswd 简 单 实现 ， 相 信 可 以 很 快 修改 成 功 。 本 章 主要 还 是 集中 在 前 端 Kibana 页 面 功 


的 实现 上 ， 主 要 包括 以 下 内 容 : 


* Kibana 索 引 的 数据 结构 。 相 比 Kibana 3，Kibana 4 将 更 多 本 身 的 数据 存 到 了 Elas-ticseatch 索 引 里 ， 本 节 介绍 .kipana 索 引 里 的 各 种 数据 ， 


法 。 
页 入 口 。 以 主页 为 入 口 介绍 Kibana 4 的 页 面 设计 。 
“discovert 解 析 。 解 析 Discovetr 页 上 使 用 的 关键 接口 和 通用 对 和 象 。 
“ visualize 解 析 。 介 绍 Visualize 页 上 使 用 的 关键 接口 ， 以 及 Visualize 页 是 如 何 融 合 d3.js 图 表 绘 制 技术 的 。 
* dashboard 解 析 。 介 绍 Dashboard 页 的 实现 要 点 。 
setting 解 析 。 介 绍 Setting 页 的 实现 ， 以 及 如 何 修 收 Setting 页 代码 ， 开 启 对 scripted field 的 语言 选择 编辑 功能 。 
参考 阅读 


时 一 定 要 设置 这 个 


setting 等 操作 的 服务 器 后 端 


至 少 是 阅读 并 理解 了 Kibana 3 源码 剖析 章节 的 内 容 ， 所 以 不 会 再 解释 有 关 Angular 的 route、controller、directive、service、factory 等 概念 。 


Ee 


对 该 索引 的 导入 导出 操作 ， 也 是 Kibana AUR 3 2- F 66 — Ae 


在 Elastic{ON} 大 会 上 ， 也 有 专门 针对 Kibana 4 源码 和 二 次 开发 入 门 的 演讲 。 请 参阅 : https:/ /speakerdeck.com/elastic/the-contributors-guide-to-the-kibana-galaxy a 


另外 ， 可 以 看 看 专业 的 前 端 工 程 师 怎 么 理解 Kibana 4 代码 的 : http://www.debuggerstep through.com/2015/04/reviewing-kibana-4s-client-side-code.html。 


19.1 Kibana 索 引 的 数据 结构 


Kibana 4 和 Kibana 3 不 同 ，Kibana 4 的 所 有 配置 项 ， 都 能 且 只 能 保存 到 Elasticsearch 索 引 中 。 在 我 们 尚 不 了 解 源码 之 前 ， 可 以 先 通 过 ES 索引 数据 ， 了 解 一 下 其 中 的 配置 数据 种 类 ， 在 稍 后 源码 阅读 中 ， 


相互 参照 。 


Kibana 4 的 配置 索引 ， 也 改 了 个 名 字 ， 叫 .kibana， 注 意 前 面 多 出 的 这 个 点 ， 这 意味 着 你 在 Linux 服 务 器 上 ， 默 认 是 看 不 到 这 个 索引 的 实际 目录 的 ， 也 算是 一 种 对 重要 数据 的 保护 方式 吧 。 


.kibana 索 引 的 结构 比 Kibana 3 的 kibana-int 索 引 要 复杂 得 多 ， 索 引 下 包括 了 以 下 几 种 类 型 : 
config _id 为 Kibana 4 的 version。 内 容 主 要 是 defaultIndex， 设 置 默 认 的 index_pattern。 
"search _id 为 discover 上 保存 的 搜索 名 称 。 内 容 主 要 是 title、column、sort 和 kibanaSavedObjectMeta。kibanaSavedObjectMeta 内 是 一 个 searchSourceJSON， 保存 搜 索 json 的 字符 囊 。 


* visualization ”_id 为 visualize 上 保存 的 可 视 化 名 称 。 内 容 包 括 title、savedSearchId、kibanaSavedObjectMeta 和 visState。 其 中 visState 里 保存 了 聚合 json 的 字符 事 。 如 果 绑 定 了 已 保存 的 搜索 ， 那 么 把 其 在 search 
类 型 里 的 _id 存 在 savedSearchId 字 段 里 ， 如 果 是 从 新 搜索 开始 的 ， 那 么 把 搜索 json 的 字符 串 直 接 存 在 自己 的 kibanaSavedObjectMeta 的 searchSourceJSON 里 。 


- dashboard _id 为 dashboard 上 保存 的 仪表 盘 名 称 。 内 容 包 括 title、panelsJSON 和 kibanaSavedObjectMeta。 其 中 panelsJSON 是 一 个 数组 ， 每 个 元 素 是 一 个 panel 的 属性 定义 。 定 义 包 括 有 : 
“type: 具体 加 载 的 app 类 型 ， 就 默认 来 说 ， 肯 定 就 是 search 或 者 visualization 之 一 。 
“ id: 具体 加 载 的 app 的 保存 id。 也 就 是 上 面 说 过 的 ， 它 们 在 各 自 类 型 下 的 _ id 内容 。 
“ size_x; panel 的 X 轴 长 度 。Kibana 4 采用 gridster 库 做 挂件 的 动态 划分 ， 默 认为 3。 
"size y: panel 的 Y 轴 长 度 ， 默 认为 2。 
“col: panel 的 左边 侧 起 始 位 置 。Kibana 4 指定 col 最 大 为 12。 每 行 第 一 个 panel 的 col 就 是 !， 假 如 它 的 size_x 是 4， 那 么 第 二 个 panel 的 col 就 是 5。 
“ row: panel 位 于 第 几 行 。gridster 默 认 的 row 最 大 为 15。 


“ index-pattern _id 为 setting 中 设置 的 index pattern。 内 容 主要 是 匹配 该 模式 的 所 有 索引 的 全 部 字段 与 字段 映射 。 如 果 是 基于 时 间 的 索引 模式 ， 还 会 有 主 时 间 字 段 timeFieldName 和 时 间 间 隔 intervalName 两 个 


field 数 组 中 ， 每 个 元 素 是 一 个 字段 的 情况 ， 包 括 字段 的 type、name、indexed、analyzed、doc values、count 和 scripted 这 些 状态 。 


如 果 scripted 为 true， 那 么 这 个 元 素 就 是 通过 Kibana 4 页 面 添加 的 脚本 化 字段 ， 那 么 这 条 字段 记录 还 会 额外 多 几 个 内 容 : 


“ script: 记录 实际 sctipt 语 句 。 


“ lang: 在 Elasticsearch 的 datanode 上 采用 什么 lang-plugin 运 行 ， 默认 是 expression。 即 EElasticsearch 1.4.4 开 始 默认 启用 的 Lucene expression。 在 目前 的 Kibana 4 页 面 上 ， 不 提供 对 这 个 的 修改 ， 所 以 统一 都 是 


这 个 值 。 


“ type: 因为 Lucene expression 目 前 只 支持 对 数值 型 字段 做 操作 ， 所 以 目前 Kibana 4 页 面 上 也 不 提供 对 这 个 的 修改 ， 直 接 默 认为 “number” 。 


对 确认 要 使 用 其 他 lang-plugin 的 ， 目 前 来 说 ， 可 以 自行 修改 kibana_index 里 的 index-pattern 类 型 中 的 数据 ， 修 改 成 “lang”: "groovy" , "type" : “string” 即 可 。 页 面 上 是 可 以 通用 的 。 


本 书 第 14 章 介绍 packetbeat 时 提 到 的 自 带 dashboard 导 入 脚本 ， 其 实 就 是 通过 curl 命 令 ， 上 传 这 些 type 的 JSON 数 据 到 指定 Elasticsearch 集 群 的 .kibana 索 引 里 。 


19:2 ERAH 


Kibana 4 已 经 是 一 个 完整 的 项 目 ， 无 法 像 单 页 的 Kibana 3 一 样 简单 地 从 目录 结构 看 出 来 组 件 分 布 。 所 以 ， 阅 读 Kibana 4 代码 ， 只 能 从 主页 入 口 开始 。 分 析 方 法 跟 Kibana 3 一 样 ， 看 index.html 和 
require.configjs 即 可 。 由 此 可 以 看 到 ， 首 先进 入 的 ， 应 该 是 indexjs。 


19.2.1 indexjs 解 析 


indexjs 主 要 分 为 两 大 块 功能 : route 设 置 和 kibana 插 件 加 载 ， 下 面 分 别 介绍 。 
1.route 设 置 


indexjs 根 据 configFile 设 置 默认 routes， 设 置 要 求 的 Elasticsearch 版 本 等 常量 : 


var configFile = JSON.parse (require ( 'text!config' ) ) ; 
var kibana = modules.get ( 'kibana', [ 

'elasticsearch', 

'pasvaz.bindonce', 


'ngRoute', 
'ngClipboard' 
D 
kibana 
.constant ('kbnVersion', window.KIBANA VERSION) 
.constant ('minimumElasticsearchVersion', '1.6.0' ) 


.constant ( 'sessionId', Date.now () ) 

.config (routes.config) ; 
routes 

.otherwise ({ 
redirectTo: '/' + configFile.default app id 
p; 


n] 


设置 routes 的 具体 操作 在 加 载 的 utils/routes/index.js 文 件 里 ， 其 中 会 调用 utils/routes/_setup.js， 在 未 设置 default index pattern 时 ， 跳 转 URL 到 “/settings/indices” 页 面 : 


handleKnownError: function (err) { 
if (err instanceof NoDefaultIndexPattern || err instanceof NoDefinedIndexPatterns) { 
kbnUrl.change ( '/settings/indices' ) ; 
) eise ( 
return Promise.reject (err) ; 
} 
} 


此 外 ，utils/routes/index.js 还 会 加 载 components/setup/setup.js 完 成 整个 环境 的 检查 和 启动 (在 Kibana 4.0 时 ， 是 在 第 二 步 kibana plugin 加 载 的 ，4.1 开 始 往 前 挪 到 这 里 ) 。setup 过 程 包 括 : 


var checkForEs = Private (require ( 'components/setup/steps/check for es’” ) ) ; 
var checkEsVersion = Private (require ( 'components/setup/steps/check es version' ) ) ; 
var checkForKibanaIndex - Private (require ( 'components/setup/steps/check for 

kibana index' ) ) ; "m 


var createKibanalIndex = Private (require ( 'components/setup/steps/create kibana index! ) ) ; 
return .once (function () ( u 
return checkForEs () 
.then (checkEsVersion) 
.then (checkForKibanaIndex) 
.then (function (exists) { 
if (! exists) return createKibanaIndex () ; 
) 
p; 


依次 调用 components/setup/steps/ 下 的 check_for es, check es version, check for kibana_index， 如 果 没 有 kibana index ( 即 上 节 讲 的 .kibana 索 引 ) , RH/EFH— T create kibana index, 


2.kibana 插 件 加 载 
kibana.load = _.onceWithCb (function (cb) ( 
var firstLoad = [ 'plugins/kibana/index' ]; 
var thenLoad = .difference (configFile.plugins, firstLoad) ; 


require (firstLoad, function loadApps () { 
require (thenLoad, cb) ; 

D 
B 


执行 kibana.load () 函数 ， 先 加 载 pluginskibanayindexjs， 然 后 加 载 configFile 里 定义 的 其 他 plugins。 
plugins/kibana/index.js 里 又 有 一 系列 操作 : 
1) 加 载 components/courier/courier.js 和 components/config/config.js 两 个 angular.service。 


2) hn&kplugins/kibana/ init, plugins/kibana/ appstüplugins/kibana/ timepicker, 


components/config/config.js 主 要 是 从 kibana index 里 的 “config”type 中 读 取 “kbnVersion”id 的 数据 。 这 个 “kbnVersion” 就 是 之 前 在 index.js 中 加 载 的 第 一 个 常量 ， 在 grunt build 编 译 时 会 自 
动 生 成 。plugins/kibana/_init 里 监听 application.load 事 件 ， 触 发 courier.start () 函数 。plugins/kibana/_timepicker 提 供 时 间 选 择 器 页 


Ej 


19.2.2 Courier% 


components/courier/courier.js 中 定义 了 Courier 类 。Courier 是 一 个 非常 重要 的 东西 ， 可 以 简单 理解 为 kibana 跟 ES 之 间 的 一 个 object mapper。 简 要 的 说 ，Courier 类 包括 以 下 方法 : 


function Courier () { 
var self = this; 
self.start = function () { 
searchLooper.start () ; 
docLooper.start () ; 
return this; 


H 
self.fetch = function () { 
fetch.fetchQueued (searchStrategy) . then (function () ( 
searchLooper.restart () ; 
p; 
H 
self.started = function () { 
return searchLooper.started () ; 
H 
self.stop = function () ( 
searchLooper.stop () ; 
return this; 
H 
self.createSource = function (type) { 
switch (type) ( 
case 'doc': 
return new DocSource () ; 
case 'search': 
return new SearchSource () ; 
} 
H 
self.close = function () { 
searchLooper.stop () ; 
docLooper.stop () ; 
. invoke (requestQueue, 'abort E 
if (requestQueue.length) ( 
throw new Error ('Aborting all pending requests failed.' ) ; 
l 


从 类 的 方法 中 可 以 看 出 ， 其 实 


就 是 5 个 属性 的 控制 ， 下 面 分 别 介绍 。 


1.DocSource 和 SearchSource 


继承 自 components/courierVdata_source/_abstract:js， 调 用 components/courieYdata_source/data_source/_doc_send to_esjs 完 成 跟 ES 数 据 的 交互 ， 用 来 做 savedObject 和 index_pattern 的 读 


es [method] (Params) 
.then (function (resp) { 
if (resp.status === 409) throw new errors.VersionConflict (resp) ; 
doc. storeVersion (resp. version) ; 
doc.id (resp. id) ; 
var docFetchProm; 
if (method !— 'index ') ( 
docFetchProm - doc.fetch () ; 
) eise ( 
// we already know what the response will be 
docFetchProm = Promise.resolve ({ 
id: resp. id, 
Lindex: params.index, 
source: body, 
type: params.type, 
Lversion: doc. getVersion () , 
found: true 
Hi 
} 


这 个 es 调用 了 services/es.js 中 定义 的 service， 里 面 内 容 超级 简单 ， 就 是 加 载 官方 的 elasticsearch.js 库 ， 然 后 初始 化 一 个 最 简 的 esFactory 客 户 端 ， 包 括 超时 都 设 成 了 0， 把 这 个 控制 交 给 server 端 : 


define (function (require) { 
require ( 'elasticsearch' ) ; 
var  - require ( 'lodash' ) ; 
var es; // share the client amoungst all apps 
require ( ‘modules’ ) 
get ( 'kibana', ['elasticsearch', ' kibana/config']) 
.service ('es', function (esFactory, configFile, $q) { 
if (es) return es; 
es = esFactory (1 
host: configFile.elasticsearch, 


log: 'info', 

requestTimeout: 0, 
apiVersion: '1.4' 
H; 


return es; 


ni 
2.searchLooperfiidocLooper 


分 别 给 Looper.start 方 法 传递 searchStrategy 和 docStrategy， 对 应 ES 的 /msearch 和 /_mget 请 求 。searchLooper 的 实现 如 下 : 


var fetch = Private (require ( 'components/courier/fetch/fetch' ) ) ; 
var searchStrategy = Private (require ( 'components/courier/fetch/strategy/search' ) ) ; 
var requestQueue = Private (require ( 'components/courier/ request queue’ ) ) ; 
var Looper = Private (require ( 'components/courier/looper/ looper' ) ) ; 
var searchLooper = new Looper (null, function () { 
$rootScope.$broadcast ( 'courier:searchRefresh' ) ; 
return fetch.these ( 
requestQueue.getInactive (searchStrategy) 
)j 
pi 


这 里 的 关键 方法 是 fetch.these () ， 出 自 components/courierfetchy/_fetch_thesejs， 其 中 调用 的 components/courierfetch/_call_clientjs 有 如 下 一 段 代 码 : 


Promise.map (executable, function (req) { 
return Promise.try (req.getFetchParams, void 0, req) 
.then (function (fetchParams) ( 
return (req.fetchParams = fetchParams) ; 
D; 
) 
.then (function (reqsFetchParams) { 
return strategy.reqsFetchParamsToBody (reqsFetchParams) ; 
p 


.then (function (body) { 
return (esPromise - es[strategy.clientMethod] (( 
timeout: configFile.shard timeout, 
ignore unavailable: true, 
preference: sessionId, 
body: body 
0); 
p 
.then (function (clientResp) { 
return strategy.getResponses (clientResp) ; 
p 
.then (respond) 


在 这 段 代 码 中 ， 我 们 可 以 看 到 strategy.reqsFetchParamsToBody () . strategy.getResponses () 和 strategy.clientMethod， 正 是 之 前 searchLooper 和 docLooper 传 递 的 对 象 属性 。 而 最 终 发 送 请 
同样 用 的 是 前 面 解释 过 的 es 这 个 service。 


bi 


此 外 ，Courier 还 提供 了 自动 刷新 的 控制 功能 : 


self.fetchInterval = function (ms) ( 
searchLooper.ms (ms) ; 
return this; 
] 
$rootScope.$watchCollection ( 'timefilter.refreshInterval', function () { 
var refreshValue = .get ($rootScope, 'timefilter.refreshInterval.value' ) ; 
var refreshPause = .get ($rootScope, 'timefilter.refreshInterval.pause ') ; 
if ( .isNumber (refreshValue) && !refreshPause) { 
self.fetchInterval (refreshValue) ; 
) else ( 
self.fetchInterval (0) ; 
} 
]) ; 


19.2.3 路径 记忆 功能 的 实现 


在 plugins/kibana/_appsjs 中 ， 我 们 可 以 看 到 路 径 记 忆 功 能 是 怎么 实现 的 : 


function appKey (app) { 
return 'lastPath:' + app.id; 
l 
function assignPaths (app) { 
app.rootPath = '/' + app.id; 
app.lastPath = sessionStorage.get (appKey (app) ) || app.rootPath; 
return app.lastPath; 
} 
function getShow (app) { 
app.show = app.order >= 0 ? true : false; 
} 
function setLastPath (app, path) { 
app.lastPath = path; 
return sessionStorage.set (appKey (app) , path) ; 
l 
$scope.apps = Private (require ( 'registry/apps' ) ) ; 
// initialize each apps lastPath (fetch it from storage) 
$scope.apps.forEach (assignPaths) ; 
$scope.apps.forEach (getShow) ; 
function onRouteChange () { 
var route = $location.path () . split (/V//) ; 
$scope.apps.forEach (function (app) ( 
if (app.active = app.id === route[1]) { 
$rootScope.activeApp = app; 
} 
D; 
if (! $rootScope.activeApp || $scope.appEmbedded) return; 
setLastPath ($rootScope.activeApp, globalState.removeFromUrl ($location.url () ) ) ; 


} 
$rootScope.$on ( '$routeChangeSuccess', onRouteChange) ; 
$rootScope.$on ('$routeUpdate', onRouteChange) ; 


这 里 使 用 的 sessionStorage 是 HTML5 自 带 的 新 特性 ， 这 样 ， 每 次 标签 页 切换 上 时， 都 可 以 把 $location.url 保 存 下 来 。 至 于 整个 Kibana 页 面 上 标签 页 的 初始 状态 ， 则 通过 registry/apps.js 获 取 。 


19.2.4 ”标签 页 应 用 的 加 载 


各 标签 页 应 用 是 怎么 进入 registry/apps 里 的 呢 ? 


之 前 我 们 已 经 说 过 ，index.js 一 开始 加 载 完 kibana 以 后 ， 会 挨个 儿 请 求 (configFile.plugins) 。 这 个 configFile.plugins 按 说 应 该 列 出 各 个 标签 页 ， 但 实际 上 ，Kibana 4 的 配置 文件 
server/config/kibana.yml 里 并 没有 一 个 参数 叫 plugins。 所 以 ， 还 得 看 看 server 端 的 实现 了 。 


和 阅读 Kibana 主 页 入 口 一 样 ， 找 到 server 端 的 主 入 口 server/indexjs: 


server/index.js: 
var requirePlugins = require ( './lib/plugins/require plugins' ) ; 
var extendHapi = require ( './lib/extend hapi' ) ; 
function Kibana (settings, plugins) { 
plugins = plugins || []; 
this.server = new Hapi.Server () ; 
extendHapi (this.server) ; 
var config = this.server.config () ; 
if (settings) config.set (settings) ; 
this.plugins = []; 
var externalPluginsFolder - config.get ( 'kibana.externalPluginsFolder' ) ; 
if (externalPluginsFolder) { 


this.plugins =  ([externalPluginsFolder]) 
.flatten () ^ 
.map (requirePlugins) 
.flatten () 
.value () ; 


} 
this.plugins = this.plugins.concat (plugins) ; 


根据 这 段 代 码 ， 我 们 知道 Kibana 4 的 Server 端 统一 也 有 插件 机 制 ， 由 server/lib/plugins/require_plugins.js 加 载 内 置 server 插 件 ， 然 后 再 加 上 外 部 server 揪 件 目录 。requirePlugins 中 查找 内 置 插件 的 方 
法 如 下 : 


globPath = globPath || join ( dirname, '', '', 'plugins', '*', 'index.js ^) ; 
return glob.sync (globPath) . map (function (file) ( 

var module = require (file) ; 

var regex = new RegExp (° ([^/]*) /index.js ') ; 

var matches - file.match (regex) ; 

if (! module.name && matches) { 

module.name = matches[1]; 

} 

l 


T 
S 
回 


也 就 是 说 ， 加 载 server/plugins/ 下 所 有 子 目 录 的 index.js。 目 前 Kibana 4 自 带 的 有 : config, elasticsearch, static, status, 43381} 
server 端 各 插件 状态 。 


config 数 据 、 代 理 ES 请 求 、 处 理 纯 静 态 文件 请 求 、 显 示 


我 们 具体 看 这 个 server/plugins/config/index.js 的 内 容 : 


var listPlugins = require ( '//lib/plugins/list plugins' ) ; 
module.exports = new kibana.Plugin (( 
init: function (server, options) { 
server.route ({ 
method: 'GET', 
path: '/config', 
handler: function (request, reply) ( 
var config = server.config () ; 
reply (( 
kibana index: config.get ( 'kibana.index' ) , 
default app id: config.get ( 'kibana.defaultAppId' ) , 
shard timeout: config.get ( 'elasticsearch.shardTimeout' ) , 
plugins: listPlugins (server) 


ps 


很 明显 ， 一 个 标准 的 node.js 的 route， 用 来 响应 对 “/config” 这 个 地 址 的 GET 请 求 ， 返 回 一 个 哈 希 JSON， 其 中 就 有 plugins。 没 错 ， 我 们 前 面 说 的 configFiles.plugins 就 是 从 这 里 获取 的 。 


下 面 看 这 个 listPlugins 的 实现 : 


var config = server.config () ; 

var bundled plugins = plugins (config.get ( 'kibana.bundledPluginsFolder' ) ) ; 

var external plugins -  (server.plugins) . map (function (plugin, name) ( 
return plugin.self && plugin.self.publicPlugins || []; 

}) o flatten () 。 value () ; 


这 个 “bundledPluginsFolder” 也 不 是 kibana.yml 里 存在 的 参数 设置 。 所 以 ， 还 得 看 上 面 这 行 server.config () 了 。 回 到 最 早先 的 server/index.js 里 ， 其 实在 require_plugins 后 面 ， 还 有 一 个 
extend_hapi。Hapi 是 node.js 的 一 个 可 扩展 框架 。 我 们 看 到 index.js 中 ， 正 是 在 extendHapi (this.server) 后 第 一 次 获取 了 server.config () 。 


extendHapi 只 有 两 行 : 
server.decorate ( 'server', 'config', require ('./config ) ) ; 
server.decorate ( 'server', 'loadKibanaPlugins', require (' ./plugins/load kibana plugins' POS 


这 个 server/lib/config/indexjs 主 要 加 载 同 目录 下 的 : config.js 用 来 实现 Config 类 ，schema.js 用 来 实现 具体 的 Joi 对 象 。 


然后 我 们 看 这 个 server/lib/config/schemajs， 就 会 发 现 各 种 配置 属性 全 在 这 里 了 。 和 搬 件 路 径 相关 的 几 行 如 下 : 


var publicFolder = path.resolve (_ dirname, '', '', 'public Ty x 
if (! checkPath (publicFolder) ) publicFolder = path.resolve ( dirname, '', '', 
te 'kibana' ) ; 


var bundledPluginsFolder = path.resolve (publicFolder, 'plugins ') ; 
module.exports = Joi.object (( 
kibana: Joi.object ({ 
bundledPluginsFolder: Joi.string () . default (bundledPluginsFolder) , 


这 里 有 两 个 路 径 ， 因 为 一 个 是 源码 位 置 ， 一 个 是 grunt build 编 译 后 的 位 置 。 就 我 们 阅读 源码 来 说 ， 这 个 _dirname/http://www.hzcourse.com/resource/readBook? 
path-/openresources/teach ebook/uncompressed/15426/OEBPS/Text/../http://www.hzcourse.com/resource/readBook? 
path-/openresources/teach ebook/uncompressed/15426/OEBPS/Text/../http://www.hzcourse.com/resource/readBook? 
path=/openresources/teach ebook/uncompressed/15426/OEBPS/Text/../kibana/plugins 就 是 我 们 最 终 找到 的 地 方 了 ， 我 们 从 server 端 源码 里 找 了 一 圈 ， 终 于 回 到 kibana 前 端 页 面 的 源码 目录 中 ， 这 
就 是 kibana/plugins 目 录 ， 自 动 加 载 其 下 所 有 子 目录 为 内 置 应 用 。 包 括 : dashboard. discover, doc, kbn vislib vis types, kibana, markdown vis, metric vis, settings, table vis, 


vis debug spy, visualize, 


除 kibana 以 外 ， 随 意 进 一 个 ， (还 记得 indexjs 里 把 kibana 去 掉 了 吧 ) ， 比 如 visualize， 看 visualize/index.js 的 内 容 ， 最 底下 有 这 么 一 段 : 


var apps = require ( 'registry/apps' ) ; 
apps.register (function VisualizeAppModule () ( 
return ( 
id: 'visualize', 


name: 'Visualize', 
order: 1 

H 
p; 


其 他 目录 也 都 一 样 。 


这 个 registry/apps.js 主 要 是 加 载 registry/_registryjs， 把 注册 的 app 存 入 utils/indexed_array/index 的 IndexedArray 对 象 。 对 象 主要 有 几 个 值 : id、name 和 order。 前 面 说 到 的 路 径 记忆 功能 的 两 
个 方法 ，assignPaths 里 就 是 用 app.id 设 置 lastPath， 而 getShow 里 就 是 用 order 来 判断 是 否 展示 在 页 面 上 。 


下 一 节 ， 我 们 开始 介绍 官方 提供 的 几 个 app。 


19.3 ”Discover 解 析 


plugins/discover/index.js 中 主要 就 是 注册 自己 的 id、name、order 到 上 节 最 后 说 的 registry.apps 里 。 此 外 就 是 加 载 本 app 目 录 内 的 其 他 文件 。 依 次 说 明 如 下 。 


1.plugins/discover/saved searches/saved searches.js 


1) 定义 savedSearches 这 个 angular service， 用 来 操作 kibana_index 索 引 里 search 这 个 类 型 下 的 数据 。 


2) 加 载 了 saved_searches/_saved_searches.js 提 供 的 savedSearch 这 个 angular factory， 这 里 定义 了 一 个 搜索 (search) 在 kibana_index 里 的 数据 结构 ， 包 括 title、description、hits、column、 
sort、version 等 字段 (这 部 分 内 容 ， 可 以 直接 通过 读 取 Elasticsearch 中 的 索引 内 容 看 到 ， 比 阅读 代码 更 直接 。19.1 节 刚刚 介绍 过 kibana_index 中 的 数据 结构 ) ， 是 不 是 有 点 眼熟 ? 没 错 ， 这 个 savedSearch 
就 是 继承 了 上 一 节 我 们 介绍 的 那个 courier 的 savedObject: 


module.factory ( ‘SavedSearch', function (courier) { 
..Class (SavedSearch) . inherits (courier.SavedObject) ; 
function SavedSearch (id) { 


3) 还 加 载 并 注册 了 plugins/settings/saved_object_registryjs， 表 示 可 以 在 settings 里 修改 这 里 的 savedSearches 对 象 。 
2.plugins/discover/directives/timechart.js 


1) 加 载 components/vislib/index.js。 


2) 提供 discoverTimechart 这 个 angular directive， 监 听 “data” 并 调用 vislib.Chart 对 象 绘 | 


D 


vislib.Chart 是 整个 Kibana 4 可 视 化 的 实现 部 分 ，19.4 节 会 更 详细 地 讲解 。 
3.plugins/discover/components/field chooser/field chooser.js 


1) f&fitdiscFieldChooserix^*angular directive, Er: 


监听 “fields” 并 fieldCalculator 计 算 常用 字段 排行 ;这 有 段 排序 计算 ， 极 具 链 式 风格 ， 又 展现 了 lodash.js 关 于 数组 的 各 类 方法 ， 摘 录 如 下 : 


_.chain (fields) 

.each (function (field) ( 
field.displayOrder =  .indexOf (columns, field.name) + 1; 
field.display = !!field.displayOrder; 
field.rowCount = fieldCounts[field.name]; 


} 

.sortBy (function (field) { 

return (field.count || 0) * -1; 

p 

.groupBy (function (field) { 

if (field.display) return 'selected'; 

return field.count » 0 ? 'popular' : 'unpopular'; 
p 

.tap (function (groups) { 


groups.selected = .sortBy (groups.selected || [], 'displayOrder ') ; 
groups.popular = groups.popular || []; 
groups.unpopular = groups.unpopular || []; 


var extras = groups.popular.splice (config.get ('fields:popularLimit' ) ) ; 
groups.unpopular = extras.concat (groups.unpopular) ; 
) 


.each (function (group, name) { 
$scope[name + 'Fields'] = .sortBy (group, name === 'selected' ? 'display' : 'name ') ; 


.commit () ; 


监听 “data” 并 调用 $scope.details () 方法 ; 提供 $scope.runAgg() 方法 。 方 法 中 ， 根 据 字段 的 类 型 不 同 ， 分 别 可 能 使 用 date_histogram/geohash_grid/terms 聚 合 函 数 ， 创 建 可 视 化 模型 ， 然 后 
带 着 当前 页 这 些 设 定 一 一 前 面 说 过 ， 各 app 之 间 通 过 globalState 共 享 状态 。 也 就 是 URL 中 的 a= (http://www.hzcourse.com/resource/readBook? 
path=/openresources/teach_ ebook/uncompressed/15426/OEBPS/Text/..) 。 各 app 会 通过 rison.decode ($location.search () . a) 和 rison.encode ($location.search () . a) 设置 和 读 取 一 一 跳 
转 到 “/visualize/create” 页 面 ， 相 当 于 是 这 三 个 常用 聚合 的 快速 可 视 化 操作 。 


默认 的 create 页 的 rison 如 下 : 


$location.path ( '/visualize/create' ) 。search ({ 
indexPattern: $scope.state.index, 
type: type, 
_a: rison.encode ({ 
filters: $scope.state.filters || [], 
query: $scope.state.query || undefined, 
vis: ( 
type: type, 
agas: [ 
agg, 
(schema: 'metric', type: 'count', 'id': '2'} 


之 前 18.8 节 的 url 示 例 中 ， 读 者 如 果 注 意 的 话 ， 会 发 现 id 是 从 2 开始 的 ， 原 因 即 在 此 。 


2) 加 载 pluginsdiscovercomponents/field_ chooser/lib/field calculator.js, $&f&fieldCalculator.getFieldValueCounts () 方法 ， 在 $scope.details () 中 读 取 被 点 击 的 字段 值 的 情况 。 


3) fini&plugins/discover/components/field chooser/discover field.js, $&fftdiscoverFieldix^*angular directive, f 


ik) ， 同 时 给 被 点 击 的 字段 加 常 
的 runAgg () 方法 。 


Æ; 加 载 plugins/discover/components/field chooser/lib/detail views/string.html 网 页 ， 


var detailsHtml = require ( 'text!plugins/discover/components/field chooser/lib/ 
detail views/string.html' ) ; 7 

$scope.toggleDetails = function (field, recompute) 
if ( .isUndefined (field.details) || recompute) 

// This is inherited from fieldChooser 

$scope.details (field, recompute) ; 

detailScope.$destroy () ; 

detailScope = $scope.$new () ; 

detailScope.warnings = getWarnings (field) ; 

detailsElem = $ (detailsHtml) ; 

$compile (detailsElem) (detailScope) ; 

$elem.append (detailsElem) ; 

else ( 

delete field.details; 

detailsElem.remove () ; 


{ 
í 


H 


弹出 浮 层 展示 零 时 的 visualize (调用 上 一 条 提供 的 $scope.details () 77 
于 浮 层 效果 。 网 页 中 对 indexed 或 scripted 类 型 的 字段 ， 可 以 调用 前 面 提 到 


4) 加 载 并 演 染 plugins/discover/components/field_chooserfield_chooser.html 网 页 。 网 页 中 使 有 


4.plugins/discover/controllers/discover.js 


加 载 了 诸多 js， 


EF 要 做 了 : 


1) 73 "/discover/: id” 提 供 route 并 加 载 plugins/discover/index.html 网 页 。 


2) 提供 discover 这 个 angular controller。 


图 


。 Visualize 中 还 会 经 常 


3) 加 载 components/vis/visjs 并 在 setupVisualization 函 数 中 绘制 histogram 


到 这 里 的 vis.aggs: 


了 上 一 条 提供 的 discover-field 标 签 。 


var visStateAggs [ 
{ 
type: 'count', 
schema: 'metric' 
) 
{ 
type: 'date_histogram', 
schema: 'segment', 
params: { 
field: $scope.opts.timefield, 
interval: $state.interval, 
min doc count: 0 
} 
} 
1; 
$scope.vis = new Vis ($scope.indexPattern, ( 
type: 'histogram', 
params: { 
addLegend: false, 
addTimeMarker: true 
Hh 
listeners: { 
click: function (e) { 
timefilter.time.from = moment (e.point.x) ; 
timefilter.time.to = moment (e.point.x + e.data.ordered.interval) ; 
timefilter.time.mode - 'absolute'; 
brush: brushEvent 
b 
aggs: visStateAggs 
Di 
$scope.searchSource.aggs (function 
$scope.vis.requesting () ; 
return $scope.vis.aggs.toDsl () ; 


s 


O t 


成 不 同 的 filter 语 句 ， 存 在 全 


局 state 里 


4) 加 载 components/filter manager/filter managerjs， 根 据 字 段 类 型 4 


5) 加 载 components/doc table/lib/get sortjs。 (存疑 : docTable 这 个 directive 是 在 哪里 加 载 的 ? ) 


19.4 Visualize 解 析 


当然 是 注册 


indexjs 中 ， 首 
到 /visualize/step/1。 


1.wizard 页 面 


己 。 此 外 ， 还 加 载 两 部 分 功能 : plugins/visualize/editoreditorjs 和 plugins/visualize/wizard/wizard.js。 然 后 定义 了 一 个 route， 默 认 跳 转 /visualize 


wizard 页 面 也 就 是 我 们 在 Visualize 标 签 页 上 创建 可 视 化 时 前 两 步 选 择 可 视 化 类 型 和 绑 定 搜索 id 的 页 面 。 在 wizard.js 中 提供 两 个 route 和 对 应 的 controller。 分 别 是 /visualize/step/1 对 应 


VisualizeWizardStep1，/visualize/step/2 对 应 VisualizeWizardStep2。 这 两 个 的 最 终结 果 都 是 跳 转 到 /visualize/createtype=* 下 。 


2.editorra 


editor 页 面 是 最 后 的 实际 可 视 化 编辑 展示 页 面 。editorjs 中 也 定义 了 两 个 route， 分 别 是 


il 


/visualize/create&[]/visualize/edit/: id。 然 后 还 定义 了 一 个 controller， 叫 作 VisEditor， 对 应 的 HTML 是 plugins/visualize/editoreditor.html， 其 


editor-sidebar。 


savedVisualizations.get ($route.current.params.id) 。 


IR] 


下 面 ， 开 始 介绍 Kibana 4 最 重要 的 可 视 化 部 分 ， 看 看 ES 响应 数据 ， 是 如 何 变 成 漂亮 的 d3.js 绘 


19.4.1 vis types 实 现 


其 中 create 是 先 加 载 registry/vis_ types， 并 检查 $route.current.params.type 是 否 存在 ， 然 后 调用 savedVisualizations.get ($route.current.params) 方法 ; 而 edit 是 直接 调 有 


到 两 个 directive， 分 别 是 visualize 和 vis- 


F 


m 


际 注册 了 vis_types 的 地 方 包括 : 
lugins/table_vis/index.js 
lugins/ metric_vis/index.js 


lugins/markdown_vis/index.js 


lugins/kbn_vislib_vis_types/index.js 


前 三 个 是 表单 ， 最 后 一 个 是 可 视 化 图 。 内 容 如 下 : 


define (function (require) { 
var visTypes = require ( 'registry/vis types' ) ; 
visTypes.register (require ( 'plugins/kbn vislib vis types/histogram ) ) ; 
visTypes.register (require ( 'plugins/kbn vislib vis types/line' ) ) ; 
visTypes.register (require ( 'plugins/kbn ib vis types/pie' ) ) ; 
visTypes.register (require ( 'plugins/kbn vislib vis types/area' ) ) ; 
visTypes.register (require ( 'plugins/kbn vislib vis types/tileMap' ) ) ; 
H); 


以 histogram 为 例 解释 一 下 visTypes。 下 面 的 实现 较 长 ， 我 们 拆 成 三 部 分 : 


第 一 部 分 ， 加 载 并 生成 VislibVisType 对 象 : 


define (function (require) ( 
return function HistogramVisType (Private) { 
var VislibVisType = Private (require ( 'components/vislib vis type/VislibVisType' ) ) ; 
var Schemas = Private (require ( 'components/vis/Schemas' ) ) ; 
return new VislibVisType (( 
name: 'histogram', 
title: 'Vertical bar chart', 
icon: 'fa-bar-chart', 
description: 'The goto chart for oh-so-many needs. Great for time and 
non-time data. Stacked or grouped, exact numbers or percentages. If 
you are not sure which chart your need, you could do worse than to 
start here.', 


第 二 部 分 ，histogram 可 视 化 所 接受 的 参数 默认 值 以 及 对 应 的 参数 编辑 页 面 : 


params: ( 

defaults: { 
ShareYAxis: true, 
addTooltip: true, 
addLegend: true, 
Scale: 'linear', 
mode: 'stacked', 
times: [], 
addTimeMarker: false, 
defaultYExtents: false, 
setYExtents: false, 
yAxis: {} 


D 
Scales: ['linear', 'log', 'square root'], 
modes: ['stacked', 'percentage', 'grouped'], ， 
editor: require ( 'text!plugins/kbn vislib vis types/editors/histogram.html' ) 
Lh 


第 三 部 分 ，histogram 可 视 化 能 接受 的 Schema。 一 般 来 说，metric 数 值 聚合 肯定 是 Y 轴 ; bucket 聚 合 肯 定 是 X 轴 ; 而 在 此 基础 上 ，Kibana 4 还 可 以 让 bucket 有 不 同 效果 ， 也 就 是 通过 设置 Schema 里 的 
segment (默认 ) 、group 和 split。 根 据 效果 不 同 ， 这 里 是 各 有 增 减 的 ， 比 如 饼 图 就 不 会 有 group， 如 下 所 示 :: 


schemas: new Schemas ([ 
{ 
group: 'metrics', 
name: 'metric', 
title: 'Y-Axis', 
min: 1, 
aggFilter: '!std_dev', 
defaults: [ T 
{ schema: 'metric', type: 'count' } 
] 
] 
{ 
group: 'buckets', 
name: 'segment', 
title: 'X-Axis', 
min: 0, 
max: 1, 
aggFilter: '!geohash_grid' 


r 


group: 'buckets', 

name: 'group', 

title: 'Split Bars', 

min: D; 

max: 1, 

aggFilter: '!geohash grid' 


b 


f 
group: 'buckets', 
name: 'split', 
title: 'Split Chart', 
min: 0, 
max: 1, 
aggFilter: '!geohash grid' 


这 里 使 用 的 VislibVisType 类 继承 自 components/vis/VisType.js，VisType.js 内 容 如 下 : 


define (function (require) { 
return function VisTypeFactory (Private) { 

var VisTypeSchemas = Private (require ( 'components/vis/Schemas' ) ) ; 

function VisType (opts) { 
opts = opts || {}; 
this.name = opts.name; 
this.title = opts.title; 
this.responseConverter = opts.responseConverter; 
this.hierarchicalData = opts.hierarchicalData || false; 
this.icon = opts.icon; 
this.description - opts.description; 
this.schemas = opts.schemas || new VisTypeSchemas () ; 


this.params = opts.params || (); 
this.requiresSearch - opts.requiresSearch — null ? true : opts.requiresSearch; 
// 默认 为 true 
} 
return VisType; 
H 
D; 


基本 跟 上 面 histogram 的 示例 一 致 ， 注 意 这 里 面 的 responseConverter 和 hierarchicalData， 是 给 不 同 的 visType 做 相应 数据 转换 的 。 在 实际 的 VislibVisType 中 ， 就 有 下 面 一 段 : 


if (this.responseConverter == null) ( 
this.responseConverter - pointSeries; 


} 


可 见 默认 情况 下 ，Kibana 4 是 尝试 把 聚合 结果 转换 成 点 线 图 数组 的 。 


VislibVisType 中 另 一 部 分 ， 则 是 扩展 了 一 个 自己 的 方法 createRenderbot， 用 来 生成 VislibRenderbot 对 象 。 这 个 类 的 实现 在 components/vislib vis type/VislibRenderbot,js， 其 中 最 关键 的 几 行 是 : 


var buildChartData = Private (require ( 'components/vislib vis type/buildChartData' ) ) ; = 
self.vislibVis = new vislib.Vis (self.$el[0], self.vislibParams) ; … 
VislibRenderbot.prototype.buildChartData = buildChartData; 
VislibRenderbot.prototype.render = function (esResponse) { 

this.chartData = this.buildChartData (esResponse) ; 

this.vislibVis.render (this.chartData) ; 
H 


也 就 是 说 ， 分 为 两 部 分 ，buildChartData 方 法 和 vislib.Vis 对 象 。 


先 来 看 buildChartData 的 实现 : 


var aggResponse = Private (require ( 'components/agg response/index' ) ) ; 
return function (esResponse) { 
var vis = this.vis; 
if (vis.isHierarchical () ) ( 
return aggResponse.hierarchical (vis, esResponse) ; 
} 
var converted = convertTableGroup (vis, tableGroup) ; 
return converted; 
H 
function convertTable (vis, table) { 
return vis.type.responseConverter (vis, table) ; 


} 


又 看 到 responseConverter 和 hierarchical 这 两 个 熟悉 的 字眼 了 ， 不 过 这 


回 


是 另 一 个 对 象 的 方法 ， 那 么 我 们 继续 跟踪 下 去 ， 看 看 这 个 aggResponse 类 是 怎么 回 


define (function (require) { 
return function NormalizeChartDataFactory (Private) { 
return ( 
hierarchical: Private (require ( 'components/agg response/hierarchical/build 
hierarchical data' ) ) , B 
pointSeries: Private (require ( 'components/agg response/point series/point series' ) ) , 
tabify: Private (require ( 'components/agg response/tabify/tabify ) ) , 
geoJson: Private (require ( 'components/agg response/geo json/geo json' ) ) 
H 
H 
D; 


然后 我 们 看 vislib.Vis 对 象 ， 定 义 在 components/vislib/vis.js 里 。 同 时 我 们 注意 到 ， 定 义 vislib 这 个 服务 的 components/vislib/index.js 里 ， 还 定义 了 一 个 服务 ， 叫 d3， 没 错 ， 我 们 离 真 正 的 绘 


visjs 中 加 载 了 components/vislib/lib/handler/handler typesfl]components/vislib/visualizations/vis types: 


D 


越 来 越 近 


var handlerTypes = Private (require ( 'components/vislib/lib/handler/handler types' ) ) ; 
var chartTypes = Private (require ( 'components/vislib/visualizations/vis types  ) ) ; 


其 中 : 


chartTypes 用 来 定义 图 : 


function Vis ($el, config) { 
if (! (this instanceof Vis) ) ( 
return new Vis ($el, config) ; 
$ 
Vis.Super.apply (this, arguments) ; 
this.el = $el.get ? $el.get (0) : $el; 
this.ChartClass = chartTypes [config. type]; 
this. attr = _.defaults ({}, config || (), {1} ; 


handlerTypes 用 来 绘制 


D 


Vis.prototype.render = function (data) { 
var chartType - this. attr.type; 
this.data - data; 
this.handler = handlerTypes[chartType] (this) || handlerTypes.column (this) ; 
this. runOnHandler ( 'render' ) ; 
H 
Vis.prototype. runOnHandler = function (method) { 
this.handler[method] () ; 
H 


components/vislib/lib/handler/handler types 中 ， 根 据 不 同 的 vis types， 分 别 返 回 不 同 的 处 理 对 象 ， 


EF 要 出 自 components/vislib/lib/handler/types/point_series、 


components/vislib/lib/handler/types/pie 和 components/vislib/lib/handler/types/tile_ map。 比 如 histogram 就 是 pointSeries.column。 可 以 看 到 point_series.js 中 ， 对 column 是 加 上 了 zeroFill: true 


和 expandLastBucket: true 参 数 调 用 create () 方法 。 而 create () 方法 中 的 new Handler () 传递 的 显然 就 是 给 d3.js 的 绘图 参数 。 而 Handler. 
components/vislib/lib/handler/handler.js 中 。Handler.prototype.render 中 有 如 下 一 段 代 码 : 


体 初始 化 和 泻 染 过 程 ， 则 在 被 加 载 的 


d3.select (this.el) 

.selectAll ( '.chart' ) 

.each (function (chartData) { 
var chart = new self.ChartClass (self, this, chartData) ; 
var enabledEvents; 
if (chart.events.dispatch) { 


enabledEvents = self.vis.eventTypes.enabled; 
d3.rebind (chart, chart.events.dispatch, 'on ') ; 
if (enabledEvents.length) ( 
enabledEvents.forEach (function (event) { 
self.enable (event, chart) ; 
n5 
} 
} 
charts.push (chart) ; 
chart.render () ; 
p 
HN 


这 里 面 的 ChartClass () 就 是 在 vislib.js 中 加 载 了 的 components/vislib/visualizations/vis_types。 它 会 根据 不 同 的 vis_types， 分 别 返 回 不 同 的 可 视 化 对 象 ， 包括: 
components/vislib/visualizations/column chart, components/vislib/visualizations/pie chart, components/vislib/visualizations/line chart, components/vislib/visualizations/area_chart 和 


components/vislib/visualizations/tile map。 这 些 对 象 都 有 同一 个 基 类 : components/vislib/visualizations/_chart， 其 中 有 这 么 一 段 代 码 : 


Chart.prototype.render = function () { 
var selection - d3.select (this.chartEl) ; 
selection.selectAll ( '*' ) 。 remove () ; 
selection.call (this.draw () ) ; 


H 


也 就 是 说 ， 各 个 可 视 化 对 象 只 需要 用 d3.js 或 者 其 他 绘 


库 ， 完 成 自己 的 draw () 函数 ， 就 可 以 了 ! 


[ 


draw 函 数 的 实现 一 般 格 式 如 下 所 示 : 


LineChart.prototype.draw = function () { 
var self - this; 
var $elem = $ (this.chartEl) ; 
var margin = this. attr.margin; 
var elWidth = this. attr.width = $elem.width () ; 
var elHeight = this. attr.height = $elem.height () ; 
var width; 
var height; 
var div; 
var svg; 
return function (selection) { 
selection.each (function (data) { 
var el - this; 
div = d3.select (el) ; 
width = elWidth - margin.left - margin.right; 
height = elHeight - margin.top - margin.bottom; 
svg = div.append ( ‘svg’ ) 
.attr ( 'width', width + margin.left + margin.right) 
.attr ('height', height + margin.top + margin.bottom) 
.append ('g ) 
.attr ( 'transform', 'translate (' + margin.left + ',' + margin.top + ° ) ^"); 


// 处 理 data 到 svg 上 


return svg; 

D; 
H 

H 


D 


当然 ,为 了 代码 逻辑 ， 有 些 比较 复杂 的 绘制 ， 还 是 会 继续 拆 分 成 其 他 文件 的 。 比 如 之 前 已 经 在 v3/bettermap 章 节 介绍 过 的 leaflet 地 | 
加 载 的 components/vislib/visualizations/_mapjs 完 成 实际 绘制 的 。 想 更 换 高 德 地 图 的 读者 ， 修 改 该 文件 中 tileLayer 变 量 的 参数 定义 (https://otile{s}-s.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}jpeg) BP 


可 


， 在 v4 中 ， 就 是 在 components/vislib/visualizations/tile_ map 里 


D 


从 数据 到 d3 演 染 ， 要 经 过 的 主要 流程 就 是 这 样 ， 散 落 在 十 多 个 不 同文 件 中 。 如 果 打 算 自己 亲手 扩展 一 个 新 的 可 视 化 方案 的 读者 ， 可 以 具体 参考 我 实现 的 sankey 
: https;///github.com/chenryn/kibana4/commit/A4eObcbeb4c8fd94807c3a0b1df2ac6f56634f9a5, 


[ 


19.4.2 savedVisualizations 实 现 


这 个 类 在 plugins/visualize/saved visualizations/saved visualizationsjs 里 定义 。 其 中 分 三 步 ， 加 载 plugins/visualize/saved visualizations/ saved vis， 注 册 到 


plugins/settings/saved object_registry， 并 定义 一 个 Angular Service 名 为 savedVisualizations 的 。 


plugins/visualize/saved visualizations/ saved vis 里 定义 了 一 个 叫 作 SavedVis 的 angular factory。 这 个 类 继承 自 courier.SavedObject， 主 要 有 _getLinkedSavedSearch 方 法 调用 savedSearches 获 
取 在 discover 中 保存 的 search 对 象 ， 以 及 visState 属 性 。 该 属性 保存 了 visualize 定 义 的 JSON 数 据 。 


savedVisualizations 里 主要 就 是 初始 化 SavedVis 对 象 ， 以 及 提供 了 一 个 find 搜 索 方法 。 整 个 实现 和 上 一 节 讲 的 savedSearches 基 本 一 样 ， 就 不 再 讲 了 。 


19.4.3 Visualize 实现 


这 个 directive 在 components/visualize/visualize.js 中 定义 ， 稍 后 我 们 还 会 再 次 提 到 这 里 。 而 我 们 可 以 上 拉 看 到 的 请 求 、 响 应 、 表 格 、 性 能 数据 ， 此 时 使 用 的 是 components/visualize/spy/spyjs 中 定 
义 的 另 一 个 directive visualizeSpy。 


真正 画图 的 地 方 ， 反 而 没有 用 directive (Kibana 3 里 用 了 ) ， 而 是 定义 了 一 个 普通 的 div， 其 class 为 visualize-chart， 在 visualize.js 中 ， 通 过 getter ('.visualize-chart') 方法 获取 div 元 素 : 


function getter (selector) { 
return function () { 
var $sel = $el.find (selector) ; 


if ($sel.size () ) return $sel; 
H 
} > 
var getVisEl = getter ( '.visualize-chart' ) ; 
然后 创建 一 个 renderbot: 


$scope.$watch ( 'vis', prereq (function (vis, oldVis) { 
var $visEl = getVisEl () ; 
if (! $visEl) return; 
if (! attr.editableVis) ( 
$scope.editableVis = vis; 


} 
if (oldVis) $scope.renderbot = null; 
if (vis) Sscope.renderbot = vis.type.createRenderbot (vis, $visEl) ; 


pos 


最 后 在 searchSource 对 象 发 生变 化 ， 即 有 新 的 搜索 响应 返回 时 ， 完 成 泻 染 。 


$scope.$watch ( 'searchSource', prereq (function (searchSource) { 
if (! searchSource || attr.esResp) return; 
searchSource.onResults () . then (function onResults (resp) { 
if ($scope.searchSource !== searchSource) return; 
$scope.esResp = resp; 
return searchSource.onResults () . then (onResults) ; 
}) ə catch (notify.fatal) ; 
searchSource.onError (notify.error) . catch (notify.fatal) ; 


Jj» 8 


$scope.$watch ('esResp', prereq (function (resp, prevResp) { 


if (! resp) return; 


$scope.renderbot.render (resp) ; 


Hyi 


19.444 VisEditorSidebar 实 现 


这 个 directive 在 plugins/visualize/editor/sidebar.js 中 定义 。 对 应 的 HTML 是 plugins/visualize/editor/sidebar.html， 其 中 又 


到 两 个 directive， 分 别 是 vis-editor-agg-group 和 vis-editor-vis- 


options。 它 们 分 别 由 sidebar.js 加 载 的 plugins/visualize/editor/agg_group 和 plugins/visualize/editor/vis_options 提 供 。 然 后 继续 操作 HTML-> directive， 基 本 上 plugins/visualize/editor/ 目 录 下 那 堆 
agg*.js 和 agg*.html 都 是 做 这 个 用 的 。 


其 中 比较 有 意思 的 ， 应 该 算是 agg_add.js。 我 们 都 知道 ，Kibana 4 最 大 的 特点 就 是 可 以 层 堵 子 聚合 ， 


这 个 操作 就 是 在 这 里 完成 的 : 


.directive ( 'visEditorAggAdd', function (Private) { 
var AggConfig = Private (require ('components/vis/AggConfig! ) ) ; 


return ( 
restrict: 'E', 


template: require ( 'text!plugins/visualize/editor/agg add.html' ) , 


controllerAs: 'add' 


, 


controller: function ($scope) ( 


var self - this; 


self.submit = function (schema) { 
var aggConfig = new AggConfig ($scope.vis, ( 
Schema: schema 


pi 


aggConfig.brandNew - true; 


H 


$scope.vis.aggs.push (aggConfig) ; 


另 一 个 比 


agg_params 选 项 。 比 如 ， 选 择 date_histogram ， 字 段 就 只 能 是 @timestamp 这 种 date 类 型 的 字段 。 


要 的 是 plugins/visualize/editovagg_paramsjs。 其 中 加 载 了 components/agg_types/indexjs， 又 监听 了 “agg.type” 变 量 ， 也 就 是 实现 了 选择 不 同 的 agg_types 时 ， 提 供 不 同 的 


components/agg typesVindexjs 中 定义 了 所 有 可 选 agg_types 的 类 。 其 中 metrics 包 括 : count、avg、sum、min、max、std_deviation、cardinality、percentiles 和 percentile_rank， 具 体 实现 分 


别 存在 components/agg_types/metrics/ 目 录 下 的 同名 .js 文件 里 ; buckets 包 括 : date histogram, histogram, range, date range, ip range, terms, filters, significant terms 和 geo_hash， 


实现 分 别 存 在 components/agg_types/buckets/ 目 录 下 的 同名 .js 文件 里 。 


这 些 类 定义 中 ， 都 有 比较 类 似 的 格式 ， 其 中 params 数 组 的 第 一 个 元 素 ， 都 是 类 似 这 样 : 


体 


{ 


name: 'field', 


filterFieldTypes: 'string' 


} 


terms.js 里 还 多 了 一 行 scriptable: true， 而 且 filterFieldTypes 是 数组 。 


{ 


name: 'field', 
scriptable: true, 


filterFieldTypes: ['number', 'boolean', 'date', 'ip', 'string'] 


} 


这 个 filterFieldTypes 在 components/vis/_agg_config.js 中 ， 通 过 fieldTypefFilter (this.vis.indexPattern.fields, fieldParam.filterFieldTypes) ; 得 到 可 选 字段 列表 。fieldTypeFitter 的 


filters/filed typejs 中 。 


19.5 “Dashboard 解 析 


plugins/dashboard/index.js 结 构 跟 Visualize 类 似 ， 注 册 到 registry; 设置 两 个 调 有 


saved-Dashboards.get () 方法 的 routes， 提 供 一 个 directive。 


savedDashboards 由 plugins/dashboard/services/saved_dashboardjs 提 供 ， 同 样 也 是 继承 saved-Object， 主 要 内 容 是 panelsJSON 数 组 字段 。 实 现 如 下 : 


体 实现 在 


module.factory ( 'SavedDashboard', function (courier) { 
.class (SavedDashboard) . inherits (courier.SavedObject) ; 
function SavedDashboard (id) ( 
courier.SavedObject.call (this, ( 
type: SavedDashboard.type, 
mapping: SavedDashboard.mapping, 
searchSource: SavedDashboard.searchsource, 


Ts. xd; 
defaults: ( 


title: 'New Dashboard', 


hits: 0, 
description: '' 
panelsJSON: '[] 
version: 1, 


, 


D 


timeRestore: false, 
timeTo: undefined, 
timeFrom: undefined 


l 


clearSavedIndexPattern: true 


D; 
} 


注意 ， 这 个 panelsJSON 是 一 个 字符 串 ， 这 跟 之 前 kibana_index 提 到 的 是 一 致 的 。 


在 dashboard-app 中 ,最 


jm 


要 的 功能 是 监听 搜索 框 和 过 滤 条 件 的 变更 ， 我 们 可 以 看 到 init 函 数 中 有 下 


面 这 段 代码 : 


function updateQueryOnRootSource () { 
var filters = queryFilter.getFilters () ; 


$scope.$listen (queryFilter, 


if ($state.query) ( 


dash.searchSource.set ( 'filter', 


query: $state.query 
]]) ) ; 


} eise ( 


[{ 


_.union (filters, 


dash.searchSource.set ('filter', filters) ; 


J 
} 


updateQueryOnRootSource () ; 
$state.save () ; 


pi 


'update', function 


O t 


在 index.html 里 ， 实 际 承载 面板 的 ， 是 下 面 这 行 代码 : 


<dashboard-grid></dashboard-grid> 


这 也 是 一 个 angular directive， 通 过 加 载 plugins/dashboard/directives/gridjs 引 入 。 其 中 添加 面板 相关 的 代码 有 两 部 分 : 


$scope.$watchCollection ( 'state.panels', function 
var currentPanels - gridster.$widgets.toArray () 


return getPanelFor (el) ; 
D; 


var added = 


(panels) ( 


. map (function (el) ( 


.difference (panels, currentPanels) ; 


if (added.length) added.forEach (addPanel) ; 
p; 
这 段 用 来 监听 $state.panels 数 组 ， 一 旦 有 新 增 面板 ， 调 用 addPanel 函 数 。 同 理 也 有 删除 面板 的 ， 这 里 就 不 重复 介绍 了 。 
而 addPanel 函 数 的 实现 大 致 如 下 : 


var addPanel = function 


m 


(panel) 
.defaults (panel, ( 

^ size x: 3, 

size y: 2 

D; 

panel.$scope = 

panel.$scope.panel = panel; 


panel.$el = $compile ( '«li»«dashboard-panel»«/li»' ) 


$scope.Snew () ; 


{ 


(panel.$scope) ; 


gridster.add widget (panel.$el, panel.size x, panel.size y, panel.col, panel.row) ; 


这 里 又 引入 了 一 个 新 的 directive， 叫 作 dashboard-panel。 


dashboard-panel 在 plugins/dashboard/components/panel/panel.js 中 实现 ， 


其 中 使 


<visualize ng-switch-when= “visualization” 


vis- "savedObj.vis" 


search-source- "savedObj.searchSource" 


class= "panel-content" > 
</visualize> 


<doc-table ng-switch-when= “search” 
search-source= "savedObj.searchSource" 


sorting= “panel.sort” 

columns= “panel.columns” 

class= “panel-content” 

filter= “filter” > 
</doc-table> 


了 plugins/dashboard/components/panel/panel.htmlI 页 面 。 


页 


面 最 后 是 这 么 一 段 : 


这 


文 里 使 


的 savedObj 对 象 , 来 


plugins/dashboard/components/panel/lib/load_panel.js 获 取 的 savedSearch 或 者 savedVisualization。 获 得 的 对 象 ， 以 savedVisualization 为 例 : 


define (function (require) { 


return function visualizationLoader (savedVisualizations, 


services here 
return function 


Private) 


(panel, $scope) ( 


return savedVisualizations.get (panel.id) 


.then (function 


return ( 
savedObj: savedVis, 
panel: panel, 
editUrl: 


savedVisualizations 


(savedVis) { 
savedVis.vis.listeners.click - 
savedVis.vis.listeners.brush - 


filterBarClickHandler ($scope.state) ; 
brushEvent; 


.urlFor (panel.id) 


( // Inject 


visualize 和 doc-table 这 两 个 directive 正 是 之 前 在 visualize 和 discover 插 件 解析 里 提 到 过 的 ， 在 components/ 底 下 实现 。 


所 以 ， 在 Dashboard 上 看 到 的 效果 就 跟 在 Visualize 和 Discover 上 看 到 的 效果 一 模 一 样 ， 因 


19.6 setting 解析 


/settings/indices 的 route， 提 供 一 个 KbnSettingsApp 的 directive。 其 中 关联 到 plugins/settings/sections/index.js 内 注册 的 indices、advanced、objects、about 四 个 


plugins/settings/index.js 结 构 跟 Visualize 类 似 ， 注 册 到 Registry; 设置 默认 跳 转 到 


因为 结构 基本 类 似 ， 这 里 只 介绍 一 个 比较 有 趣 的 地 方 。indices 中 的 scripted field， 原 本 的 设计 中 ， 是 利 上 
现 安全 漏洞 ，Elasticsearch 紧 急 取消 掉 了 groovy 的 默认 开 | 


启 设置 。 同 理 ，plugins/settings/sections/indices/scripted fields/index. 


为 用 的 是 同样 的 directive。 


但 是 ， 如 果 私 有 集群 在 防火 墙 内 部 ， 依 然 可 以 开启 groovy sandbox， 其 实 还 可 以 继续 使 


么 不 


到 的 


修改 Kibana 4 源码 ， 就 能 继续 使 


内 容 。 看 起 来 似乎 没有 定义 选 


。 在 稍 


groovy sandbox 来 支持 的 。 但 是 就 在 Kibana 4 正式 
js 里 也 改 成 了 “expression” 3 


后 的 章节 中 ， 我 们 会 介绍 如 何 直接 修改 kibana_index。 而 这 旦 


scripted field 的 修改 页 面 ， 在 plugins/settings/sections/indices/_scripted _fields.js。 这 里 面 的 $scope.columns 数 组 ， 包 括 name、script、type、popularity 和 controls 五 列 ， 也 就 是 我 们 在 页 
的 引擎 。 


区 块 。 


ig. 


Ej 


版 要 发 布 的 几 天 前 ，groovy sandboxtH 


里 ， 我 们 则 深入 理解 相关 代码 ， 介 绍 为 什 


上 看 


Ej 


那 往 上 一 层 ， 看 scripted fieldfRX A D1plugins/settings/sections/indices/scripted fields/index;jsEB, fE$scope.submit () 方法 里 ， 我 们 可 以 看 到 下 面 一 段 代 码 : 


var field = .defaults ($scope.scriptedField, { 
type: 'number', 
lang: 'expression' 
n; 
try ( 
if (createMode) { 
$scope.indexPattern.addScriptedField (field.name, field.script, field.type, field.lang) ; 
) eise ( 
$scope.indexPattern.save () ; 


$ 


没 错 ， 添 加 scripted field 到 index pattern 的 过 程 就 是 这 里 ! 我 们 可 以 看 到 ， 这 里 是 有 field.lang 设 定 的 。 只 不 过 


默认 值 是 expression 而 已 。 


现在 就 去 看 plugins/settings/sections/indices/scripted fields/index.html 里 关于 $scope.scripted-Field 是 怎么 处 理 的 : 


«form name= "scriptedFieldForm' ng-submit= "submit () ”> 
«div class= "form-group' > 
Xlabel»Name«/label» 
«input required type- “text” ng-model- *scriptedField.name' class= “form- 
control spanl2" > 
</div> 
<div class= “form-group” > 
<textarea required class= “scripted-field-script form-control span12” ng- 
model= “scriptedField.script” ></textarea> 
</div> 
</form> 
<div class= “form-group” > 
<button class= “btn btn-primary” ng-click= “goBack () ” >Cancel</button> 
<button class= “btn btn-success' ng-click- “submit () " ng-disabled= “scriptedFiel 
dForm. $invalid” > 
Save Scripted Field 
</button> 
</div> 


HTML 里 只 提供 了 name 和 script 两 个 值 的 输入 框 ! 也 就 是 说 ，Kibana 4 只 是 不 提供 让 你 输入 groovy 到 field.lang 的 文本 框 而 已 。 
所 以 ， 如 果 你 有 随时 定义 scripted field 的 需求 ， 又 嫌弃 每 次 cur| 直 接 修改 kibana_index 太 麻烦 还 可 能 出 错 ， 那 么 你 只 需要 稍微 修改 几 处 Kibana 4 代码 就 够 了 : 
1) f£plugins/settings/sections/indices/scripted fields/index.html 里 提供 对 scriptedField.lang 和 scriptedField.type 的 输入 框 。 


2) 在 plugins/settings/sections/indices/_scripted fields.js 里 给 $scope.columns 数 组 和 addRow 方 法 都 加 上 field.lang 字 段 的 展示 。 


